Руководство пользователя KatePart

# Руководство пользователя KatePart

Thad McGinnis `<ctmcginnis@compuserve.com>`

Anne-Marie Mahfouf `<annma@kde.org>`

Anders Lund `<anders@alweb.dk>`

T.C. Hollingsworth `<tchollingsworth@gmail.com>`

developer: Christoph Cullmann
reviewer: Lauri Watts
Перевод на русский язык: Екатерина Пыжова
Обновление перевода: Олег Баталов
Обновление перевода: Виктор Ерёмин
Редактирование перевода: Олеся Герасименко
Издание Frameworks
5.94 (2 мая 2022 г.)

Авторские права © 2000, 2001 Thad McGinnis

Авторские права © 2005 Anne-Marie Mahfouf `<annma@kde.org>`, Anders Lund `<anders@alweb.dk>`

Авторские права © 2011, 2012, 2013, 2014 T.C. Hollingsworth `<tchollingsworth@gmail.com>`

Юридическое уведомление

KatePart — полнофункциональный компонент редактирования KDE.

Список примеров

5.1. Примеры использования команды char
5.2. Замена текста в текущей строке
5.3. Замена текста во всём файле
5.4. Более сложный пример
5.5. sort в сравнении с natsort
5.6. Объединить выделенные строки
5.7. Удалить пустые строки
5.8. Удалить пустые строки

Глава 1. Введение
Введение

# Глава 1. Введение

KatePart — это полнофункциональный компонент редактирования, который используется различными приложениями Qt™ и KDE. KatePart представляет собой не просто текстовый редактор: приложение создавалось для использования программистами и может считаться, по крайней мере, частичной альтернативой более мощным редакторам. Одна из главных особенностей KWrite — это подсветка синтаксиса, настроенная для множества разных языков программирования, таких как C/C++, Java™, Python, Perl, Bash, Modula 2, HTML и Ada.

KWrite — простой текстовый редактор, созданный на основе KatePart. В его окне возможно работать одновременно только с одним документом (SDI). Так как редактор KWrite представляет собой очень простую реализацию KatePart, для него не требуется отдельная документация. Если освоить работу в KWrite, будет возможно использовать KatePart где угодно!

Глава 2. Основы
Основы

# Глава 2. Основы

Работа с KWrite и многими другими модулями Kate очень проста. При наличии опыта работы с текстовым редактором проблем возникнуть не должно.

## Перетаскивание

KatePart поддерживает протокол перетаскивания мышью KDE. Файлы возможно перетащить в KatePart с рабочего стола, из диспетчера файлов Dolphin или с какого-либо сетевого FTP-сайта, открытого в окне Dolphin.

Комбинации клавиш
Комбинации клавиш

## Комбинации клавиш

Многие комбинации клавиш возможно перенастроить с помощью меню Настройка. По умолчанию комбинации клавиш в KatePart настроены следующим образом:

Ins | Переключение между режимами вставки и замены. В режиме вставки редактор будет добавлять все вводимые символы, перемещая текст справа от курсора дальше. В режиме замены каждый вводимый символ будет удалять символ справа от курсора.
Стрелка влево | Переместить курсор на символ влево.
Стрелка вправо | Переместить курсор на символ вправо.
Стрелка вверх | Переместить курсор на строку выше.
Стрелка вниз | Переместить курсор на строку ниже.
Ctrl+E | Перейти к предыдущему редактируемому месту в документе.
Ctrl+Shift+E | Перейти к следующему редактируемому месту в документе.
Alt+Shift+Стрелка вверх | Переместить курсор к предыдущему совпадающему отступу.
Alt+Shift+Стрелка вниз | Переместить курсор к предыдущему совпадающему отступу.
Ctrl+6 | Переместить курсор к парной скобке.
PgUp | Переместить курсор на страницу выше.
PgDn | Переместить курсор на страницу ниже.
Home | Переместить курсор к началу текущей строки.
End | Переместить курсор к концу текущей строки.
Ctrl+Home | Перейти к началу документа.
Ctrl+End | Перейти к концу документа.
Ctrl+Стрелка вверх | Прокрутить строку вверх.
Ctrl+Стрелка вниз | Прокрутить строку вниз.
Ctrl+Стрелка вправо | Переместить слово вправо.
Ctrl+Стрелка влево | Переместить слово влево.
Ctrl+Shift+Стрелка вверх | Переместить строки вверх.
Ctrl+Shift+Стрелка вниз | Переместить строки вниз.
Ctrl+. | Дублировать выделенные строки ниже.
Ctrl+B | Установить закладку.
Alt+PgUp | Предыдущая закладка.
Alt+PgDn | Следующая закладка.
Del | Удалить символ справа от курсора (или выделенный текст).
Backspace | Удалить символ слева от курсора.
Ctrl+Del | Удалить слово справа.
Ctrl+Backspace | Удалить слово слева.
Ctrl+K | Удалить строку.

Shift+Enter

Вставить символ начала новой строки, включая начальные символы текущей строки, отличные от букв или цифр. Эта возможность полезна при написании комментариев в коде: в конце строки «// какой-либо текст» используйте эту комбинацию клавиш, и следующая строка уже будет начинаться с символов «// ». Поэтому символы комментария не потребуется вводить в начале каждой новой строки комментариев.

Ctrl+Shift+Enter | Создать новую строку под текущей.
Ctrl+Alt+Enter | Создать новую строку над текущей.
Shift+Стрелка влево | Выделить символ слева от курсора.
Shift+Стрелка вправо | Выделить символ справа от курсора.
Ctrl+F | Найти.
F3 | Следующее совпадение.
Shift+F3 | Предыдущее совпадение.
Ctrl+H | Найти выделенное.
Ctrl+Shift+H | Найти выделенное (в обратном направлении).
Ctrl+Shift+Стрелка вправо | Выделить слово справа.
Ctrl+Shift+Стрелка влево | Выделить слово слева.
Shift+Home | Выделить до начала строки.
Shift+End | Выделить до конца строки.
Shift+Стрелка вверх | Выделить до предыдущей строки.
Shift+Стрелка вниз | Выделить до следующей строки.
Ctrl+Shift+6 | Выделить до парной скобки.
Ctrl+Shift+PgUp | Выделить до начала области просмотра.
Ctrl+Shift+PgDn | Выделить до конца области просмотра.
Shift+PgUp | Выделить страницу вверх.
Shift+PgDn | Выделить страницу вниз.
Ctrl+Shift+Home | Выделить до начала документа.
Ctrl+Shift+End | Выделить до конца документа.
Ctrl+Home | Выделить всё.
Ctrl+Shift+A | Снять выделение.
Ctrl+Shift+B | Блочное выделение.
Ctrl+C / Ctrl+Ins | Скопировать выделенный текст в буфер обмена.
Ctrl+D | Закомментировать.
Ctrl+Shift+D | Раскомментировать.
Ctrl+G | Перейти на строку
Ctrl+I | Вставить отступ для выделенного фрагмента.
Ctrl+Shift+I | Снять отступ для выделенного фрагмента.
Ctrl+J | Объединить строки.
Ctrl+P | Печать.
Ctrl+R | Замена.
Ctrl+S | Выполнить команду Сохранить.
Ctrl+Shift+S | Сохранить как.
Ctrl+U | Перевести в верхний регистр.
Ctrl+Shift+U | Перевести в нижний регистр.
Ctrl+Alt+U | С заглавной буквы.
Ctrl+V / Shift+Ins | Вставить текст из буфера обмена.
Ctrl+X / Shift+Ins | Скопировать выделенный текст в буфер обмена и удалить его из документа.
Ctrl+Z | Отменить.
Ctrl+Shift+Z | Повторить.
Ctrl+- | Уменьшить размер шрифта.
Ctrl++Ctrl+= | Увеличить размер шрифта.
Ctrl+Shift+- | Свернуть узлы верхнего уровня.
Ctrl+Shift++ | Развернуть узлы верхнего уровня.
Ctrl+Пробел | Завершение кода.
F5 | Обновить.
F6 | Показать/скрыть полосу отметок.
F7 | Переключиться в командную строку.
F9 | Показать/скрыть полосу сворачивания блоков.
F10 | Динамический перенос строк.
F11 | Показать/скрыть номера строк.
Ctrl+T | Переставить символы.
Ctrl+Shift+O | Автопроверка орфографии.
Ctrl+Shift+V | Перейти к следующему режиму ввода.
Ctrl+8 | Повторить слово выше.
Ctrl+9 | Повторить слово ниже.
Ctrl+Alt+# | Развернуть аббревиатуру.
Ctrl+Alt+Стрелка вверх | Добавить курсор над текущим.
Ctrl+Alt+Стрелка вниз | Добавить курсор под текущим.
Shift+Alt+I | Создать курсор в конце каждой строки в выбранном фрагменте.
Alt+J | Найти следующее вхождение слова под курсором и выбрать его.
Ctrl+Alt+Shift+J | Найти все вхождения слова под курсором и выбрать их.

Глава 3. Работа с редактором KatePart
Работа с редактором KatePart

# Глава 3. Работа с редактором KatePart

Anders Lund `<anders@alweb.dk>`

Dominik Haumann `<dhdev@gmx.de>`

Перевод на русский язык: Андрей Балагута
Обновление и редактирование перевода: Олеся Герасименко

## Обзор

Редактор KatePart — это область редактирования в главном окне KatePart. Этот редактор используется как в Kate, так и в KWrite, а также в Konqueror для отображения текстовых файлов, расположенных на локальном компьютере или в сети.

Редактор состоит из следующих частей:

Область редактирования

  Здесь отображается текст документа.

Полосы прокрутки

  Полосы прокрутки показывают положение видимой части текста документа; они используются для перемещения по документу. При перемещении ползунка курсор вставки остаётся на месте.

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

Полоса закладок

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

  Чтобы установить или убрать закладку на какой-либо строке, щёлкните левой кнопкой мыши по полосе закладок напротив этой строки.

  Отображение полосы закладок возможно включить или отключить с помощью пункта меню Вид → Полоса закладок.

Панель номеров строк

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

  Отображение панели номеров строк возможно включить или отключить с помощью пункта меню Вид → Номера строк.

Полоса сворачивания блоков

  Полоса сворачивания блоков позволяет сворачивать и разворачивать отдельные блоки кода. Группировка строк в блоки осуществляется на основе правил подсветки синтаксиса.

Содержание этой главы:

- Навигация по тексту

- Работа с выделением

- Копирование и вставка текста

- Поиск и замена текста

- Использование закладок

- Автоматический перенос по словам

- Использование автоматической расстановки отступов

Навигация по тексту
Навигация по тексту

## Навигация по тексту

Перемещение по тексту в KatePart выполняется так же, как и в большинстве текстовых редакторов с графическим интерфейсом: с помощью клавиш со стрелками и клавиш Page Up, Page Down, Home, End, а также их разных комбинаций с клавишами Ctrl и Shift. Клавиша Shift позволяет выделять текст, а работа Ctrl зависит от конкретной клавиши, с которой она выступает в комбинации:

- Для клавиш Вверх и Вниз: прокрутка документа вместо перемещения курсора.

- Для клавиш Влево и Вправо: перемещение по словам, а не по символам.

- Для клавиш Page Up и Page Down: перемещение на край видимой области.

- Для клавиш Home и End: перемещение в начало или конец документа, а не строки.

KatePart также предоставляет возможность перехода от открывающей скобки (в том числе фигурной и квадратной) к соответствующей закрывающей и наоборот: поместите курсор непосредственно перед скобкой или после неё (обе скобки должны выделиться жёлтым фоном) и нажмите Ctrl+6.

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

Работа с выделением
Работа с выделением

## Работа с выделением

В KatePart существует два основных способа выделения текста: с помощью мыши и с помощью клавиатуры.

Чтобы выделить текст мышью, щёлкните левой кнопкой в начале текста, который следует выделить, и, не отпуская кнопку, переместите указатель мыши в конец текста. Выделенная область текста меняется по мере перемещения указателя.

Двойной щелчок левой кнопкой мыши позволяет выделить слово.

Тройной щелчок выделяет всю строку.

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

- Если ничего не было выделено, от позиции ввода (текстовый курсор) до позиции указателя мыши.

- Если был выделен текст, то от начала этого выделенного фрагмента и до позиции указателя мыши, включая сам выделенный фрагмент.

### Примечание

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

Чтобы выделить текст с помощью клавиатуры, удерживайте клавишу Shift при выделении нужного фрагмента с использованием клавиш навигации (клавиши со стрелками, Page Up, Page Down, Home и End, возможно, в сочетании с Ctrl).

Дополнительные сведения доступны в разделе Навигация по тексту этой главы.

Чтобы скопировать выделенный фрагмент текста, выберите пункт меню Правка → Копировать или воспользуйтесь соответствующей комбинацией клавиш (по умолчанию Ctrl+C).

Чтобы снять выделение, выберите пункт меню Правка → Снять выделение или воспользуйтесь соответствующей комбинацией клавиш (по умолчанию Ctrl+Shift+A), или просто щёлкните левой кнопкой мыши в редакторе.

### Блочное выделение

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

Чтобы включить или отключить режим блочного выделения, выберите пункт меню Правка → Блочное выделение или воспользуйтесь соответствующей комбинацией клавиш (по умолчанию Ctrl+Shift+B).

### Замена выделенного фрагмента

Если режим замены выделенного фрагмента включён, любой ввод или вставка текста приведёт к замене выделенного к этому моменту текста на новый текст. Если этот режим отключён, новый текст будет добавлен в позиции текстового курсора.

По умолчанию режим замены выделенного фрагмента включён.

Включить или отключить этот режим возможно на странице «Редактирование» диалога настройки.

### Постоянное выделение

Если режим постоянного выделения включён, ввод символов или перемещение текстового курсора не вызовет снятия выделения с ранее выделенного фрагмента. Это означает, что возможно перемещать курсор за пределы выделения и вводить текст.

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

Включить этот режим возможно на странице «Редактирование» диалога настройки.

### Предупреждение

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

Копирование и вставка текста
Копирование и вставка текста

## Копирование и вставка текста

Чтобы скопировать текст, выделите его и выберите пункт меню Правка → Копировать. Кроме того, выделенный с помощью мыши текст автоматически копируется в буфер выделения X-сервера.

Для вставки текста, находящегося в буфере обмена, выберите пункт меню Правка → Вставить.

Текст, выделенный с помощью мыши, также возможно вставить щелчком средней кнопки мыши.

### Подсказка

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

Поиск и замена текста
Поиск и замена текста

## Поиск и замена текста

### Поиск и замена

В KatePart присутствует панель пошагового поиска, а также панель расширенного поиска и замены текста, в которой возможно ввести строку замены и указать несколько дополнительных параметров.

Следующие параметры являются общими:

Искать

  Здесь следует ввести строку поиска. Интерпретация строки зависит от параметров, описание которых приводится далее.

С учётом регистра

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

На панели расширенного поиска и замены доступны несколько дополнительных опций:

Обычный текст

  Поиск буквальных совпадений со строкой поиска.

Только полные слова

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

Управляющие последовательности

  Если выбрана эта опция, в шаблон поиска будет возможно добавить управляющие последовательности из предустановленного списка. Для этого следует открыть контекстное меню поля ввода и выбрать последний пункт — Добавить (он будет доступен после выбора этой опции).

Регулярное выражение

  Если выбрана эта опция, строка поиска интерпретируется как регулярное выражение. В шаблон поиска будет возможно добавить регулярные выражения из предустановленного списка. Для этого следует открыть контекстное меню поля ввода и выбрать последний пункт — Добавить (он будет доступен после выбора этой опции).

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

Искать только в выделенном фрагменте

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

Найти все

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

### Поиск текста

Чтобы начать поиск текста, откройте панель пошагового поиска с помощью комбинации клавиш Ctrl+F или пункта меню Правка → Найти....

В нижней части окна редактора появится панель пошагового поиска. Слева от поля ввода текста расположена кнопка закрытия панели.

Поиск выполняется по мере ввода текста. Обнаруженные совпадения выделяются в тексте, при этом цвет фона поля ввода становится светло-зелёным. Если для поискового запроса не обнаружено совпадений, цвет фона поля ввода станет светло-красным.

Кнопки и позволяют перейти к следующему или предыдущему вхождению.

Обнаруженные в документе совпадения останутся выделенными даже после закрытия панели поиска. Чтобы снять это выделение, нажмите клавишу Esc.

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

Чтобы перейти к панели расширенного поиска и замены, нажмите кнопку , которая расположена с правой стороны панели пошагового поиска.

Если требуется повторить последний поисковый запрос (при наличии) без открытия панели пошагового поиска, воспользуйтесь пунктом меню Правка → Продолжить поиск (F3) или Правка → Найти предыдущее (Shift+F3).

### Замена текста

Чтобы заменить текст, откройте панель расширенного поиска и замены с помощью пункта меню Правка → Заменить... или комбинации клавиш Ctrl+R.

Слева от панели расположена кнопка закрытия панели. Рядом с ней находится небольшое поле со списком, предназначенное для указания шаблона поиска. В этом поле сохраняется информация о последних использованных шаблонах.

Режимом поиска возможно управлять с помощью следующих параметров, которые доступны в раскрывающемся списке: Обычный текст, Только полные слова, Управляющие последовательности и Регулярное выражение.

Если выбрана опция Управляющие последовательности или Регулярное выражение, в конце контекстного меню поля ввода текста будет доступен пункт Добавить.... С его помощью к шаблону поиска или замены возможно добавить управляющие последовательности или регулярные выражения из предустановленных списков.

Кнопки и позволяют перейти к следующему или предыдущему вхождению.

Введите текст, на который следует выполнить замену, в поле Заменить на и нажмите кнопку Заменить (будет заменено только текущее выделенное вхождение) Заменить все (будут заменены все вхождения в документе).

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

Чтобы перейти к панели пошагового поиска, нажмите кнопку , которая расположена с правой стороны панели расширенного поиска и замены.

### Подсказка

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

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

### Подсказка

Команды find (найти), replace (заменить) и ifind (пошаговый поиск) возможно выполнять из командной строки.

Использование закладок
Использование закладок

## Использование закладок

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

Возможно установить или убрать закладку двумя способами:

- Переместите курсор вставки на нужную строку и выберите пункт меню Закладки → Поставить закладку (Ctrl+B).

- Щёлкните по полосе закладок напротив нужной строки.

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

Для быстрого перехода между закладками выберите пункт меню Закладки → Следующая (Alt+Page Down) или Закладки → Предыдущая (Alt+Page Up).

Автоматический перенос по словам
Автоматический перенос по словам

## Автоматический перенос по словам

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

Чтобы включить или отключить эту функцию, установите или снимите флажок Переносить строки на странице «Редактирование» диалога настройки.

Чтобы указать максимальную длину строки (в символах), воспользуйтесь параметром Переносить слова на новую строку после на странице «Редактирование» диалога настройки.

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

- При наборе редактор автоматически вставит разрыв строки при достижении максимальной длины строки.

- При загрузке документа редактор автоматически разобьёт длинные строки на несколько строк нормальной длины (если они содержат пробелы — иначе перенос строк невозможен).

### Примечание

В текущей версии программы невозможно установить перенос строк только для определённых типов файлов или хотя бы ограничить действие этого параметра на уровне документа. Это будет исправлено в будущих версиях KatePart.

Использование автоматической расстановки отступов
Использование автоматической расстановки отступов

## Использование автоматической расстановки отступов

Компонент редактирования KatePart поддерживает множество различных режимов автоматической расстановки отступов для разных форматов. Выбрать один из них возможно с помощью пункта меню Сервис → Расстановка отступов. Модуль расстановки отступов также предоставляет пункт меню Сервис → Форматированный отступ, который пересчитывает отступ выделенного текста или текущей строки.

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

### Подсказка

Все такие параметры возможно задать с помощью переменных документа и типов файлов.

Доступные режимы расстановки отступов

Без автоматического отступа

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

Обычный

  Расстановка отступов аналогично предыдущей непустой строке. Этот режим возможно сочетать с установкой и отменой отступов вручную.

Стиль C

  Для исходных текстов на языке C и других подобных языках (C++, C#, Java™, JavaScript и так далее). Этот режим не будет работать со сценарными языками, такими как Perl или PHP.

Haskell

  Для языка функционального программирования Haskell.

Lilypond

  Для описания музыкальных нот на языке Lilypond.

Lisp

  Специально для сценариев на языке Lisp и диалектов Lisp.

Python

  Специально для сценариев на языке Python.

Стиль XML

  Специально для языков, близких к XML.

Маркеры изменённых строк
Маркеры изменённых строк

## Маркеры изменённых строк

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

Использование маркеров изменённых строк.

Используемые цвета возможно изменить на странице Шрифты и цвета диалога настройки. Чтобы полностью отключить показ маркеров изменённых строк, следует снять соответствующий флажок на вкладке Границы страницы Внешний вид диалога настройки.

Мини-карта в полосе прокрутки
Мини-карта в полосе прокрутки

## Мини-карта в полосе прокрутки

KatePart поддерживает отображение мини-карты в полосе прокрутки. Эта функция позволяет выполнять предварительный просмотр документа в окне, которое всплывает при наведении указателя мыши на мини-карту. Текущая видимая часть документа выделяется на мини-карте.

Предварительный просмотр исходного кода Kate с помощью мини-карты в полосе прокрутки.

Мини-карту возможно временно включить или отключить с помощью пункта меню Вид → Мини-карта в полосе прокрутки. Чтобы сделать это на постоянной основе, воспользуйтесь соответствующим флажком на странице «Внешний вид» диалога настройки KatePart.

Множественные курсоры
Множественные курсоры

## Множественные курсоры

Множественные курсоры были представлены в версии 5.93 модуля katepart.

### Создание множественных курсоров

- С помощью мыши: Alt + щелчок левой кнопкой. Модификатор можно настроить (подробнее здесь: Настройка множественного курсора).

- С помощью клавиатуры: Ctrl+Alt+Стрелка вверх для создания курсора над основным курсором и Ctrl+Alt+Стрелка вниз для создания курсора под основным курсором. Эти комбинации клавиш также можно настроить.

- Чтобы создать курсоры в выбранном фрагменте, необходимо сначала выбрать какой-либо текст и затем использовать комбинацию клавиш Shift+Alt+I: в конце каждой строки в выбранном фрагменте будет создан курсор.

- Комбинация клавиш Alt+J позволяет найти следующее вхождение слова под курсором и выбрать его + создать курсор. Чтобы пропустить текущее слово под курсором, воспользуйтесь комбинацией клавиш Alt+K; текущее выбранное слово будет отмечено в качестве пропущенного. При повторном нажатии комбинации клавиш Alt+J с текущего слова будет снято выделение и произойдёт переход к следующему слову.

- Комбинация клавиш Ctrl+Alt+Shift+J позволяет найти все вхождения слова под курсором и выбрать их, при этом в конце каждого выделения будет создан курсор. Для циклического перехода между выбранными словами можно воспользоваться комбинацией клавиш Alt+J, при необходимости снимая выделение со слов с помощью комбинации клавиш Alt+K (её описание приводилось в предыдущем абзаце).

### Работа с множественными курсорами

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

Нажатие клавиши Alt + щелчок левой кнопкой мыши позволяет удалить выбранный курсор. Если же необходимо удалить курсоры только в пустых строках, можно воспользоваться готовым действием: откройте командную строку с помощью комбинации клавиш Ctrl+Alt+I, найдите пункт Удалить курсоры из пустых строк и нажмите клавишу Enter. Также можно настроить комбинацию клавиш для этого действия.

Глава 4. Команды меню
Команды меню

# Глава 4. Команды меню

## Меню «Файл»

Файл → Создать (Ctrl+N)

  Создаёт новый документ в новом независимом окне редактора.

Файл → Новое окно

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

Файл → Открыть... (Ctrl+O)

  Вызывает стандартное диалоговое окно KDE Открыть файл. Выберите нужный файл с помощью средства просмотра файлов и нажмите кнопку Открыть для его открытия.

Файл → Последние файлы

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

Файл → Сохранить (Ctrl+S)

  Сохраняет текущий документ. Если он уже был сохранён, то старый файл будет перезаписан без предупреждения. Если документ сохраняется впервые, будет открыт диалог сохранения (подробнее об этом далее).

Файл → Сохранить как... (Ctrl+Shift+S)

  Сохраняет документ в другой файл. Для этого используется диалоговое окно со списком файлов, описание которого приведено ранее в разделе Открыть.

Файл → Сохранить в другой кодировке...

  Сохраняет документ в другой файл с другой кодировкой.

Файл → Сохранить копию как...

  Сохраняет документ в другой файл; возможно продолжить редактировать оригинальный документ.

Файл → Обновить (F5)

  Обновляет текущий файл. Эта команда удобна, если файл, открытый в KatePart, был изменён другой программой.

Файл → Печать... (Ctrl+P)

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

Файл → Экспорт в HTML...

  Сохраняет текущий документ в качестве файла HTML, отформатированного согласно текущим параметрам подсветки синтаксиса и цветовой схемы.

Файл → Закрыть (Ctrl+W)

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

Файл → Выход (Ctrl+Q)

  Закрывает окно редактора. Если были запущены другие экземпляры KatePart (с помощью пунктов меню Создать или Новое окно), соответствующие окна не будут закрыты.

Меню «Правка»
Меню «Правка»

## Меню «Правка»

Правка → Отменить действие (Ctrl+Z)

  Отменяет последнюю команду редактирования (ввод, копирование, вырезание и так далее).

  ### Примечание

  Если включён режим группировки отмены, эта команда отменяет несколько однотипных команд вроде ввода символов.

Правка → Повторить (Ctrl+Shift+Z)

  Выполняет последнее отменённое действие.

Правка → Вырезать (Ctrl+X)

  Удаляет текущий выделенный фрагмент и помещает его в буфер обмена. Буфер обмена работает незаметно и позволяет передавать данные между приложениями.

Правка → Копировать (Ctrl+C)

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

Правка → Копировать в формате HTML

  Сохраняет текущий документ в качестве файла HTML, отформатированного согласно текущим параметрам подсветки синтаксиса и цветовой схемы.

Правка → Вставить (Ctrl+V)

  Вставляет первый элемент из буфера обмена в позиции курсора. Буфер обмена работает незаметно и позволяет передавать данные между приложениями.

  ### Примечание

  Если включён режим замены выделенного фрагмента, вставленный текст заменит выделенный фрагмент (если он есть).

Правка → Вставить выделенное (Ctrl+Shift+Ins)

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

Правка → Вставить с заменой буфера обмена выделением

  Выделенный текст будет заменён содержимым буфера обмена.

Правка → Вставка из журнала буфера обмена

  Будет открыт диалог для выбора и вставки записи из журнала буфера обмена.

Правка → Режимы ввода

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

Правка → Режим замены (Ins)

  Переключает между режимами вставки и замены. Если включён режим ВСТАВКА, символы будут вставляться в позиции курсора. Если включён режим ЗАМЕНА, набираемые символы будут заменять текущие, если курсор расположен перед каким-либо символом. В строке состояния показан текущий режим: ВСТАВКА или ЗАМЕНА.

Правка → Заблокировать изменение текста

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

Правка → Найти... (Ctrl+F)

  Открывает панель поиска в нижней части окна редактора. Слева от поля ввода текста расположена кнопка закрытия панели.

  Поиск выполняется по мере ввода текста. Обнаруженные совпадения выделяются в тексте, при этом цвет фона поля ввода становится светло-зелёным. Если для поискового запроса не обнаружено совпадений, цвет фона поля ввода станет светло-красным.

  Кнопки и позволяют перейти к следующему или предыдущему вхождению.

  Обнаруженные в документе совпадения останутся выделенными даже после закрытия панели поиска. Чтобы снять это выделение, нажмите клавишу Esc.

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

  Чтобы перейти к расширенной панели поиска и замены, нажмите кнопку , которая расположена с правой стороны панели пошагового поиска.

Правка → Варианты поиска → Продолжить поиск (F3)

  Повторяет последний поисковый запрос (при наличии), не вызывая панель пошагового поиска; поиск начинается с текущей позиции курсора.

Правка → Варианты поиска → Найти предыдущее (Shift+F3)

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

Правка → Варианты поиска → Следующее вхождение выделенного текста (Ctrl+H)

  Находит следующее вхождение выделенного текста.

Правка → Варианты поиска → Предыдущее вхождение выделенного текста (Ctrl+Shift+H)

  Находит предыдущее вхождение выделенного текста.

Правка → Заменить... (Ctrl+R)

  Открывает панель расширенного поиска и замены. Слева от поля ввода текста расположена кнопка закрытия панели.

  Режимом поиска возможно управлять с помощью следующих параметров, которые доступны в раскрывающемся списке: Обычный текст, Только полные слова, Управляющие последовательности и Регулярное выражение.

  Если выбрана опция Управляющие последовательности или Регулярное выражение, в конце контекстного меню поля ввода текста будет доступен пункт Добавить.... С его помощью к шаблону поиска или замены возможно добавить управляющие последовательности или регулярные выражения из предустановленных списков.

  Кнопки и позволяют перейти к следующему или предыдущему вхождению.

  Введите текст, на который следует выполнить замену, в поле Заменить на и нажмите кнопку Заменить (будет заменено только текущее выделенное вхождение) Заменить все (будут заменены все вхождения в документе).

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

  Чтобы перейти к панели пошагового поиска, нажмите кнопку , которая расположена с правой стороны панели расширенного поиска и замены.

Меню «Выделение»
Меню «Выделение»

## Меню «Выделение»

Выделение → Выделить все (Ctrl+A)

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

Выделение → Снять выделение (Ctrl+Shift+A)

  Снимает выделение с текста (если есть).

Выделение → Блочное выделение (Ctrl+Shift+B)

  Переключает режим выделения. Когда установлен режим Блок (он обозначается тестом «[Блок]» в строке состояния), возможно выполнять вертикальное выделение, например, выделить столбцы с пятого по десятый в строках 9-15.

Выделение → Закомментировать (Ctrl+D)

  Добавляет знак комментария, отделённый от начала текста в строке пробелом.

Выделение → Раскомментировать (Ctrl+Shift+D)

  Удаляет знак комментария и пробел, которым этот знак отделялся от начала текста в строке.

Выделение → Объединить строки (Ctrl+J)

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

Выделение → Прописные буквы (Ctrl+Alt+U)

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

Выделение → Перевести в ВЕРХНИЙ РЕГИСТР (Ctrl+U)

  Переводит выделенный текст (или букву под курсором) в верхний регистр.

Выделение → Перевести в нижний регистр (Ctrl+Shift+U)

  Переводит выделенный текст (или букву под курсором) в нижний регистр.

Выделение → Привести отступы в порядок

  Исправляет отступы в выделенном фрагменте текста или в строке, на которой находится курсор. Благодаря этому действию выделенный текст будет соответствовать выбранному режиму расстановки отступов.

Выделение → Форматированный отступ

  Заново выравнивает текущую строку или строки в выделенном фрагменте согласно правилам отступа для документа.

Выделение → Выровнять по…

  Эта команда выравнивает строки в выбранном блоке или всём документе по позиции, которая указана регулярным выражением (программа выведет запрос на его ввод).

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

  Если в шаблоне есть блок захвата, для захваченного совпадения будет добавлен отступ.

  Примеры:

  При использовании «`-`» будут вставлены пробелы перед первым «-» в каждой строке, чтобы выровнять все дефисы по одной позиции.

  При использовании «`alignon :\\s+(.)`» будут вставлены пробелы перед первым непустым символом, стоящим после двоеточия, чтобы выровнять все такие символы по одной позиции.

Выделение → Выполнить перенос строк

  Включает статический перенос строк в документе. Символ новой строки будет вставлен автоматически, когда текущая строка достигнет длины, указанной на вкладке Переносить слова на новую строку после (Настройка → Настроить редактор...).

Выделение → Добавить точку вставки над курсором (Ctrl+Alt+Стрелка вверх)

  Добавляет ещё одну точку вставки над текущим курсором. Она располагается в строке выше на той же самой позиции, что и текущий курсор.

Выделение → Добавить точку вставки под курсором (Ctrl+Alt+Стрелка вниз)

  Добавляет ещё одну точку вставки под текущим курсором. Она располагается в строке ниже на той же самой позиции, что и текущий курсор.

Выделение → Добавить курсоры в конце строк (Alt+Shift+I)

  Добавляет курсор ко всем текущим выделенным строкам.

Выделение → Найти и выбрать следующее вхождение (Alt+J)

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

Выделение → Найти и выбрать все вхождения (Ctrl+Alt+Shift+J)

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

Меню «Вид»
Меню «Вид»

## Меню «Вид»

Вид → Увеличить размер шрифта (Ctrl++)

  Увеличивает размер шрифта текста документа

Вид → Уменьшить размер шрифта (Ctrl+-)

  Уменьшает размер шрифта текста документа.

Вид → Перенос строк → Динамический перенос строк (F10)

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

Вид → Перенос строк → Маркеры динамического переноса строк

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

Вид → Перенос строк → Маркеры статического переноса строк

  Если этот параметр включён, на столбце с переносимыми строками будет показана вертикальная линия (настраивается с помощью пункта меню Настройка → Настроить редактор... на вкладке «Редактирование»). Обратите внимание, маркер будет виден только в том случае, если используется моноширинный шрифт.

Вид → Границы → Полоса закладок (F6)

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

Вид → Границы → Номера строк (F11)

  Это переключаемый элемент. Если флажок установлен, слева от текста будут показаны номера строк.

Вид → Границы → Отметки на полосе прокрутки

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

Вид → Границы → Мини-карта в полосе прокрутки

  Заменяет полосу прокрутки визуализацией текущего документа. Более подробные сведения о мини-карте в полосе прокрутки: «Мини-карта в полосе прокрутки».

Вид → Сворачивание блоков кода

  Эти параметры позволяют настроить сворачивание блоков кода:

  Вид → Границы → Сворачивание блоков кода → Полоса сворачивания блоков

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

  Вид → Сворачивание блоков кода → Свернуть текущий блок кода

    Сворачивает ближайший к курсору блок.

  Вид → Сворачивание блоков кода → Развернуть текущий блок кода

    Разворачивает ближайший к курсору блок.

  Вид → Сворачивание блоков кода → Свернуть блоки 1-го уровня (Ctrl+Shift+-)

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

  Вид → Сворачивание блоков кода → Развернуть блоки 1-го уровня (Ctrl+Shift++)

    Разворачивает все блоки верхнего уровня в документе.

Показать непечатаемые пробелы

  Показывает или скрывает рамку вокруг непечатаемых пробельных символов.

Меню «Переход»
Меню «Переход»

## Меню «Переход»

Переход → Перейти на строку... (Ctrl+G)

  Открывает панель строки перехода в нижней части окна и переводит курсор на указанный пользователем номер строки в документе. Номер строки возможно ввести вручную или выбрать с помощью стрелок в правой части поля ввода. Маленькая стрелка вверх увеличивает число, маленькая стрелка вниз — уменьшает. Чтобы закрыть панель, нажмите на кнопку, расположенную в её левой части.

Переход → Перейти к предыдущему редактируемому месту в документе (Ctrl+E)

  Это действие позволяет перейти к предыдущему редактируемому месту в документе при работе с множественными курсорами.

Переход → Перейти к следующему редактируемому месту в документе (Ctrl+Shift+E)

  Это действие позволяет перейти к следующему редактируемому месту в документе при работе с множественными курсорами.

Переход → Перейти к предыдущей изменённой строке

  Строки, в которые были внесены изменения с момента открытия файла, называются изменёнными строками. Это действие позволяет перейти к предыдущей изменённой строке.

Переход → Перейти к следующей изменённой строке

  Строки, в которые были внесены изменения с момента открытия файла, называются изменёнными строками. Это действие позволяет перейти к следующей изменённой строке.

Переход → Перейти к парной скобке (Ctrl+6)

  Перемещает курсор к парной открывающей или закрывающей скобке.

Переход → Выделить до открывающей/закрывающей скобки (Ctrl+Shift+6)

  Выделяет текст между парными открывающей и закрывающей скобками.

Переход → Закладки (Ctrl+Shift+6)

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

Переход → Закладки → Поставить закладку (Ctrl+B)

  Устанавливает или удаляет закладку для текущей строки активного документа (если закладки не было, она устанавливается, если была — удаляется).

Переход → Закладки → Убрать все закладки

  Убирает все закладки из документа и из списка, который располагается в конце этого меню.

Переход → Закладки → Предыдущая (Alt+PgUp)

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

Переход → Закладки → Следующая (Alt+PgDn)

  Перемещает курсор к ближайшей следующей закладке. Пункт меню будет содержать номер строки и начало текста на ней. Этот пункт доступен, только если ниже курсора есть строка с закладкой.

Меню «Сервис»
Меню «Сервис»

## Меню «Сервис»

Сервис → Тип документа

  Позволяет выбрать тип файла для текущего документа. Переопределяет глобальный тип файла, указанный с помощью пункта меню Настройка → Настроить редактор... на вкладке «Типы файлов», но только для текущего документа.

Сервис → Подсветка

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

Сервис → Расстановка отступов

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

Сервис → Кодировка

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

Сервис → Добавлять отметку о порядке байтов (BOM)

  Позволяет явным образом добавить маркер последовательности байтов в документах, закодированных в формате Юникод. Маркер последовательности байтов — это символ из стандарта Юникод, используемый для обозначения порядка байтов в текстовом файле или потоке. Дополнительные сведения: Маркер последовательности байтов.

Сервис → Конец строки

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

Сервис → Сценарии

  Это вложенное меню содержит список сценариев. Возможно также написать собственные сценарии. Это позволяет расширить функционал KatePart инструментами, определёнными пользователем.

  Сервис → Сценарии → Навигация
    Сервис → Сценарии → Навигация → Перейти к предыдущему такому же отступу (Alt+Shift+Стрелка вверх)

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

    Сервис → Сценарии → Навигация → Перейти к следующему такому же отступу (Alt+Shift+Стрелка вниз)

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

  Сервис → Сценарии → Редактирование
    Сервис → Сценарии → Редактирование → Отсортировать выделенный текст

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

    Сервис → Сценарии → Редактирование → Переместить строки ниже (Ctrl+Shift+Стрелка вниз)

      Переместить выделенные строки ниже.

    Сервис → Сценарии → Редактирование → Переместить строки выше (Ctrl+Shift+Стрелка вверх)

      Переместить выделенные строки выше.

    Сервис → Сценарии → Редактирование → Продублировать выделенные строки ниже (Ctrl+Alt+Стрелка вниз)

      Дублирует выделенные строки ниже.

    Сервис → Сценарии → Редактирование → Продублировать выделенные строки выше (Ctrl+Alt+Стрелка вверх)

      Дублирует выделенные строки выше.

    Сервис → Сценарии → Редактирование → Закодировать выделенный текст в формат URI

      Кодирует выделенный текст таким образом, чтобы его было возможно использовать как часть строки запроса URL-адреса. Выделенный текст заменяется закодированным.

    Сервис → Сценарии → Редактирование → Декодировать выделенный текст в формате URI

      Если выделена часть строки запроса URL-адреса, она будет декодирована. Выделенный фрагмент заменяется исходным необработанным текстом.

  Сервис → Сценарии → Emmet
    Сервис → Сценарии → Emmet → Развернуть сокращение

      Преобразует выделенный текст в пару открывающих и закрывающих тегов HTML или XML. Например, если выбрано `div`, этот элемент будет заменён на `<div></div>`.

    Сервис → Сценарии → Emmet → Обернуть в тег

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

    Сервис → Сценарии → Emmet → Переместить курсор к соответствующему тегу

      Если курсор находится внутри открывающего тега HTML/XML, он будет перемещён к закрывающему тегу. Если же курсор находится внутри закрывающего тега, он будет перемещён к открывающему тегу.

    Сервис → Сценарии → Emmet → Выделить содержимое тега HTML/XML, перемещаясь внутрь

      Если курсор находится внутри пары тегов HTML/XML, выделение также будет включать и содержимое этих тегов HTML/XML (не включая сами теги).

    Сервис → Сценарии → Emmet → Выделить содержимое тега HTML/XML, перемещаясь наружу

      Если курсор находится внутри пары тегов HTML/XML, выделение также будет включать и содержимое этих тегов HTML/XML (включая сами теги).

    Сервис → Сценарии → Emmet → Закомментировать или раскомментировать

      Если выделенный текст не является комментарием, он будет обозначен как комментарий HTML/XML (например, `<!-- выделенный текст -->`). Если выделенный текст является комментарием, то соответствующие теги будут удалены.

    Сервис → Сценарии → Emmet → Удалить тег под курсором

      Если курсор находится внутри тега HTML/XML, этот тег будет удалён целиком.

    Сервис → Сценарии → Emmet → Уменьшить число на 1

      Если выделенный текст является числом, из него будет вычтена единица. Например, если выделено `5`, результатом будет `4`.

    Сервис → Сценарии → Emmet → Уменьшить число на 10

      Если выделенный текст является числом, из него будет вычтено 10. Например, если выделено `15`, результатом будет `5`.

    Сервис → Сценарии → Emmet → Уменьшить число на 0,1

      Если выделенный текст является числом, из него будет вычтено 0,1. Например, если выделено `4,5`, результатом будет `4,4`.

    Сервис → Сценарии → Emmet → Увеличить число на 1

      Если выделенный текст является числом, к нему будет прибавлена единица. Например, если выделено `5`, результатом будет `6`.

    Сервис → Сценарии → Emmet → Увеличить число на 10

      Если выделенный текст является числом, к нему будет прибавлено 10. Например, если выделено `5`, результатом будет `15`.

    Сервис → Сценарии → Emmet → Увеличить число на 0,1

      Если выделенный текст является числом, к нему будет прибавлено 0,1. Например, если выделено `4,5`, результатом будет `4,6`.

Сервис → Командная строка (F7)

  Отображает командную строку KatePart в нижней части окна. Чтобы получить справочную информацию, введите `help`, а чтобы получить список команд — `help list`. Дополнительные сведения о командной строке доступны в разделе Командная строка компонента редактирования.

Сервис → Дополнить код (Ctrl+Пробел)

  Вручную вызывает функцию дополнения кода (обычно это выполняется с помощью соответствующей комбинации клавиш).

Сервис → Автодополнение слов

  При выборе пункта Использовать нижестоящее слово (Ctrl+9) или Использовать вышестоящее слово (Ctrl+8) для дополнения введённой на данный момент части слова будет выполняться поиск похожих слов в направлении вниз или вверх от текущей позиции курсора. При выборе пункта Автодополнение как в командной оболочке появится окно с совпадающими записями.

Сервис → Орфография → Автоматическая проверка орфографии (Ctrl+Shift+O)

  Если параметр Автоматическая проверка орфографии включён, неправильно написанное слово будет подчёркнуто сразу же.

Сервис → Орфография → Проверка орфографии...

  Запускает программу проверки орфографии, которая позволяет пользователю найти и исправить орфографические ошибки. При выборе этого пункта меню будет запущена проверка и открыт диалог управления её ходом. В этом диалоге присутствуют следующие параметры:

  Неизвестное слово:

    Слово, в котором, возможно, содержится ошибка. На самом деле ошибки может и не быть, просто такого слова нет в словаре (с содержимым которого модуль сравнивает каждое проверяемое слово) модуля.

  Заменить на:

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

  Язык:

    Если установлено несколько словарей, здесь возможно выбрать, какой из них следует использовать.

  В правой части диалога расположены 6 кнопок управления проверкой орфографии:

  Добавить в словарь

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

  Похожие слова

    Список возможных замен слова с ошибкой. Если щёлкнуть по одному из вариантов, он появится в поле Заменить на.

  Заменить

    Подтвердить замену неизвестного слова текстом из поля Заменить на.

  Заменить все

    Не только заменить текущее неизвестное слово на слово в поле Заменить на, но и автоматически выполнить аналогичную замену для всех остальных вхождений этого неизвестного слова.

  Игнорировать

    Продолжить поиск ошибок, не меняя неизвестное слово.

  Игнорировать везде

    Пропустить текущее неизвестное слово и поступать аналогичным образом со всеми такими же словами в документе.

    ### Примечание

    Применяется только для текущего сеанса проверки орфографии. При следующем запуске снова будет предложено заменить это слово.

  Ещё три кнопки расположены по горизонтали, в нижней части диалога проверки орфографии:

  Справка

    Открывает справочную систему KDE на странице справки к этому диалогу.

  Готово

    Завершает процесс проверки орфографии (сохраняя все исправления).

  Отмена

    Прерывает проверку орфографии (не сохраняя исправления).

Сервис → Орфография → Проверка орфографии от курсора...

  Запускает программу проверки орфографии, но начинает проверку с позиции курсора (а не с начала документа).

Сервис → Орфография → Проверка орфографии в выделенном фрагменте...

  Проверяет орфографию в выделенном фрагменте текста.

Сервис → Орфография → Выбрать словарь...

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

Меню «Настройка» и «Справка»
Меню «Настройка» и «Справка»

## Меню «Настройка» и «Справка»

Настройка → Цветовая схема редактора

  Это меню содержит доступные схемы. Здесь возможно изменить схему для текущего документа. Чтобы изменить схему по умолчанию, откройте страницу «Шрифты и цвета» диалога настройки.

В приложении KatePart присутствуют стандартные меню KDE: Настройка и Справка. Дополнительные сведения доступны в разделе справки «Основы KDE» (подразделы Меню «Настройка» и Меню «Справка»).

Глава 5. Дополнительные возможности редактирования
Дополнительные возможности редактирования

# Глава 5. Дополнительные возможности редактирования

Anders Lund `<anders@alweb.dk>`

Dominik Haumann `<dhdev@gmx.de>`

Перевод на русский язык: Андрей Балагута
Перевод на русский язык: Алексей Опарин
Обновление перевода: Олеся Герасименко

## Комментирование

Команды Закомментировать и Раскомментировать, которые доступны в меню Сервис, позволяют добавить или убрать маркеры комментариев для выделенного блока текста (или для текущей строки, если текст не выделен) при условии, что комментарии поддерживаются форматом редактируемого текста.

Правила комментирования определяются синтаксисом; таким образом, если подсветка синтаксиса не включена, то команды «Закомментировать» и «Раскомментировать» будут недоступны.

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

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

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

Чтобы закомментировать выделенный текст (или текущую строку), выберите пункт меню Сервис → Закомментировать или воспользуйтесь соответствующей комбинацией клавиш (по умолчанию Ctrl+D).

Чтобы удалить маркеры комментариев, выберите пункт меню Сервис → Раскомментировать или воспользуйтесь соответствующей комбинацией клавиш ( по умолчанию Ctrl+Shift+D).

Командная строка компонента редактирования
Командная строка компонента редактирования

## Командная строка компонента редактирования

Компонент редактирования KatePart имеет встроенную командную строку, позволяющую производить различные действия, оставляя интерфейс минималистичным. Она представляет собой поле ввода в нижней части области редактора. Чтобы получить доступ к командной строке, выберите пункт меню Вид → Командная строка или нажмите клавишу F7 (по умолчанию). Описание доступных команд приводится далее. Кроме того, в модулях могут быть доступны дополнительные команды.

Для выполнения команды введите её и нажмите клавишу Enter. На месте команды будет выведено сообщение об успешном её выполнении или об ошибке. Если командная строка была вызвана с помощью клавиши F7, она будет автоматически скрыта по прошествии нескольких секунд. Чтобы убрать сообщение и ввести новую команду, нажмите клавишу F7 ещё раз.

Чтобы получить справку, введите команду help. Для получения списка всех доступных команд введите команду help list, для просмотра справки по определённой команде — help `команда`.

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

### Стандартные команды

Типы аргументов

BOOLEAN

  Используется для команд включения или отключения. Допустимые значения: `on`, `off`, `true`, `false`, `1` или `0`

INTEGER

  Целое число.

STRING

  Строка, заключённая в одинарные (') кавычки (или двойные (") кавычки, если она содержит пробелы).

#### Параметры редактора

Эти команды предоставляются компонентом редактирования и позволяют настроить только текущие документ и представление. Удобно, если требуется установить параметры, отличные от стандартных (например, отступ).

set-tab-width {INTEGER width}

  Устанавливает ширину табуляции.

set-indent-width {INTEGER width}

  Устанавливает ширину отступа. Только при создании отступов пробелами.

set-word-wrap-column {INTEGER width}

  Устанавливает максимальную длину строк в случае, если включён автоматический перенос.

set-icon-border {BOOLEAN enable}

  Устанавливает видимость полосы отметок.

set-folding-markers {BOOLEAN enable}

  Устанавливает видимость маркеров сворачивания блоков кода.

set-line-numbers {BOOLEAN enable}

  Устанавливает видимость нумерации строк.

set-replace-tabs {BOOLEAN enable}

  Заменять при вводе символы табуляции на пробелы.

set-remove-trailing-space {BOOLEAN enable}

  Удалять пробелы в конце строки при снятии с неё курсора.

set-show-tabs [BOOLEAN enable]

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

set-show-indent {BOOLEAN enable}

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

set-indent-spaces {BOOLEAN enable}

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

set-mixed-indent {BOOLEAN enable}

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

  Эта команда также включит расстановку отступов пробелами и установит ширину отступов, если она не указана, в половину значения `tab-width` (для текущего документа во время выполнения).

set-word-wrap {BOOLEAN enable}

  Выполнять динамический перенос строк.

set-replace-tabs-save {BOOLEAN enable }

  Заменять символы табуляции на пробелы при сохранении.

set-remove-trailing-space-save {BOOLEAN enable}

  Удалить пробелы в конце строк при сохранении.

set-indent-mode {STRING name}

  Выбрать режим расстановки отступов. Параметр `name` может иметь следующие значения: «none», «normal», «cstyle», «haskell», «lilypond», «lisp», «python», «ruby» или «xml». При указании других значений используется «none».

set-auto-ident {BOOLEAN script}

  Включить или отключить автоматическую расстановку отступов.

set-highlight {STRING highlight}

  Выбрать формат для подсветки синтаксиса (один из содержащихся в меню Сервис → Подсветка). Доступно также автозавершение параметра.

reload-scripts

  Перезагрузить сценарии JavaScript, которые используются Kate, включая сценарии расстановки отступов и сценарии командной строки.

set-mode {STRING mode}

  Выбрать тип файла для текущего документа.

nn[oremap] {STRING original} {STRING mapped}

  Сопоставить комбинацию клавиш `original` комбинации `mapped`.

#### Команды редактирования

Команды, которые непосредственно изменяют текущий документ.

indent

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

unindent

  Снять отступы с выделенных строк или с текущей.

cleanindent

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

comment

  Вставить маркеры, отмечающие выделенные строки или текущую как комментарии, в соответствии с форматом текущего файла (определяется способом подсветки синтаксиса).

uncomment

  Удалить маркеры, отмечающие выделенные строки или текущую как комментарии, в соответствии с форматом текущего файла (определяется способом подсветки синтаксиса).

kill-line

  Удалить текущую строку.

replace { STRING pattern} {STRING replacement}

  Заменить текст, совпадающий с `pattern`, на `replacement`. Чтобы включить в `pattern` пробелы, следует заключить в двойные или одинарные кавычки и `pattern`, и `replacement`. Если аргументы не заключены в кавычки, первое слово будет принято за `pattern`, а остальное — за `replacement`. Если не указать `replacement`, все вхождения `pattern` будут удалены.

  Для настройки параметров поиска следует указать соответствующие флаги после двоеточия (`replace:options pattern replacement`). Возможные параметры:

  `b`

    Искать в обратном направлении.

  `c`

    Искать от позиции курсора.

  `e`

    Искать только в выделенном тексте.

  `r`

    Аргумент `pattern` — регулярное выражение. Возможно использовать `\N` в `replacement` для получения энной подстроки найденного текста.

  `s`

    С учётом регистра.

  `p`

    Запрашивать у пользователя подтверждение каждой замены.

  `w`

    Только целые слова.

date {STRING format}

  Вставить строку с датой/временем в указанном формате (задаётся параметром `format`). Если параметр не указан, используется формат «yyyy-MM-dd hh:mm:ss». Доступны следующие подстановки:

  `d` | Номер дня в месяце без ведущего нуля (1-31).
  `dd` | Номер дня в месяце с ведущим нулём (01-31).
  `ddd` | Сокращённое локализованное название дня недели («пн»...«вс»).
  `dddd` | Полное локализованное название дня недели («понедельник»...«воскресенье»).
  `M` | Номер месяца без ведущего нуля (1-12).
  `MM` | Номер месяца с ведущим нулём (01-12).
  `MMMM` | Полное локализованное название месяца («января»...«декабря»).
  `MMM` | Сокращённое локализованное название месяца («янв.»...«дек.»).
  `yy` | Год двумя цифрами (00-99).
  `yyyy` | Год четырьмя цифрами (1752-8000).
  `h` | Час без ведущего нуля (0...23 или 1...12, в зависимости от параметра формата часов).
  `hh` | Час с ведущим нулём (00...23 или 01...12, в зависимости от параметра формата часов).
  `m` | Минуты без ведущего нуля (0...59).
  `mm` | Минуты с ведущим нулём (00...59).
  `s` | Секунды без ведущего нуля (0...59).
  `ss` | Секунды с ведущим нулём (00...59).
  `z` | Миллисекунды без ведущих нулей (0...999).
  `zzz` | Миллисекунды с ведущими нулями (000...999).
  `AP` | Использовать 12-часовой формат часов. AP будет заменено на «AM» или «PM».
  `ap` | Использовать 12-часовой формат часов. ap будет заменено на «am» или «pm».

char {STRING identifier}

  Эта команда позволяет вставить символ по его числовому идентификатору в десятичной, восьмеричной или шестнадцатеричной системах счисления. Чтобы использовать её, откройте командную строку и наберите `char [числовой_идентификатор]`.

  Пример 5.1. Примеры использования команды char

  Введите: `char 234`

  Получите: `ê`

  Введите: `char 0x1234`

  Получите: `ሴ`

s///[ig] %s///[ig]

  Попробуем разобраться в этих двух sed-подобных командах. Первая выполняет поиск/замену в текущей строке, вторая — во всём файле (%s///).

  Команды производят поиск текста, заданного маской поиска (регулярным выражением между первой и второй наклонной чертой) и, при нахождении, замену на выражение, которое задано между второй и третьей чертой. Круглые скобки в маске поиска позволяют задать подстроки в найденном тексте, на которые возможно потом ссылаться в выражении замены. Обратная ссылка — это регулярное выражение, которое при совпадении заменяется на фактический текст и может быть использовано в шаблоне замены. Для этого необходимо поставить в нужном месте обратную черту, а за ней указать номер подстроки по порядку (`\1` — для первой пары скобок, `\2` — для второй и так далее).

  Чтобы искать сами скобки `(` или `)`, следует предварить их обратной чертой: `\(\)`

  Если в самом конце указать `i`, поиск будет выполняться с учётом регистра, а если `g` — будут заменены все вхождения текста, совпадающего с регулярным выражением (иначе — только первое).

  Пример 5.2. Замена текста в текущей строке

  Предположим, что получено сообщение об ошибке компиляции: класс `myClass`, упомянутый в строке 3902, не определён.

  Добравшись до строки 3902, вместо того, чтобы пытаться найти слово `MyClass` в тексте, возможно просто открыть диалоговое окно «Команда правки», ввести `s/myclass/MyClass/i`, нажать кнопку OK, сохранить файл и выполнить компиляцию — успешно и без ошибок.

  Пример 5.3. Замена текста во всём файле

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

  Вызовите командную строку и введите следующий текст: `%s/госпожа Иванова/госпожа Петрова/` — и всё будет готово.

  Пример 5.4. Более сложный пример

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

  Допустим, набрана такая строка:

      void MyClass::DoStringOps( String      &foo, String &bar, String *p, int  &a, int &b )

  Предположим, что этот код недостаточно «красив» и решено использовать ключевое слово `const` с параметрами, передаваемыми по ссылке (теми, перед которыми стоит амперсанд), а также удалить лишние пробелы.

  Откройте диалоговое окно «Команда правки» и введите: `s/\s+(\w+)\s+(&)/ const \1 \2/g`, затем нажмите кнопку OK. Символ `g` в конце команды указывает компилятору «пересчитывать» регулярное выражение обратной ссылки каждый раз, когда встречаются совпадения.

  Вывод: `void MyClass::DoStringOps( const String &foo, const String &bar, String *p, const int &a, const int &b )`

  Всё готово! Что было сделано? Выполнялся поиск некоторого количества пробелов (`\s+`), за которыми следуют один или несколько буквенных символов (`\w+`), за которыми находятся пробелы (`\s+`), после которых расположен амперсанд, и в процессе эти буквенные символы и амперсанд сохранялись для использования в операции замены. После этого совпадающие части строки были заменены следующей последовательностью: один пробел, за которым следует спецификатор «const», за ним ещё один пробел, после которого ранее сохранённые символы (`\1`), ещё один пробел и сохранённый амперсанд (`\2`)

  В одних случаях буквенные символы составили слово «String», в других — слово «int», то есть символьный класс `\w` с последующим знаком `+` определяет символьный набор произвольной длины.

sort

  Упорядочить выделенный текст или весь документ.

natsort

  Упорядочить выделенные строки или весь документ в естественном порядке.

  Пример 5.5. sort в сравнении с natsort

  `sort(a10, a1, a2)`: результатом будет `a1, a10, a2`

  `natsort(a10, a1, a2)`: результатом будет `a1, a2, a10`

moveLinesDown

  Переместить выделенные строки ниже.

moveLinesUp

  Переместить выделенные строки выше.

uniq

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

rtrim

  Удалить пробелы в конце строк из выделенного текста или всего документа.

ltrim

  Удалить пробелы в начале строк из выделенного текста или всего документа.

join [STRING separator]

  Объединить выделенные строки или весь документ. Возможно указать параметр, который определяет разделитель, например: `join ', '`

rmblank

  Удалить все пробелы из выделенного текста или всего документа.

alignon

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

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

  Если в шаблоне есть блок захвата, для захваченного совпадения будет добавлен отступ.

  Примеры:

  `alignon -` вставит пробелы перед первым «-» в каждой строке, чтобы выровнять все дефисы по одной позиции.

  `alignon :\\s+(.)` вставит пробелы перед первым непустым символом, стоящим после двоеточия, чтобы выровнять все такие символы по одной позиции.

unwrap

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

each {STRING script}

  Вызвать указанную в качестве аргумента функцию JavaScript для списка выделенных строк и заменить их возвращаемым значением этого обратного вызова.

  Пример 5.6. Объединить выделенные строки

  `each 'function(lines){return lines.join(", ")}'`

  Или более краткий вариант:

  `each 'lines.join(", ")'`

filter {STRING script}

  Вызвать указанную в качестве аргумента функцию JavaScript для списка выделенных строк и удалить те, для которых этот обратный вызов возвращает значение false.

  Пример 5.7. Удалить пустые строки

  `filter 'function(1){return 1.length > 0;}'`

  Или более краткий вариант:

  `filter 'line.length > 0'`

map {STRING script}

  Вызвать указанную в качестве аргумента функцию JavaScript для списка выделенных строк и заменить строку значением этого обратного вызова.

  Пример 5.8. Удалить пустые строки

  `map 'function(line){return line.replace(/^s+/,"");}'`

  Или более краткий вариант:

  `map 'line.replace(/^s+/,"")'`

duplicateLinesUp

  Дублировать выделенные строки над текущим выделенным текстом.

duplicateLinesDown

  Дублировать выделенные строки под текущим выделенным текстом.

#### Команды навигации

goto {INT line}

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

grep {STRING pattern}

  Выполнить поиск регулярного выражения `pattern` в документе. Дополнительные сведения: Приложение A, Регулярные выражения.

find {STRING pattern}

  Перейти к первому вхождению, заданному параметром `pattern`. Последующие вхождения возможно найти с помощью пункта меню Правка → Продолжить поиск (клавиша по умолчанию — F3).

  Параметры команды поиска возможно настраивать с помощью добавления двоеточия и флагов после её имени (`find:options pattern`). Возможные параметры:

  `b`

    Искать в обратном направлении.

  `c`

    Искать от позиции курсора.

  `e`

    Искать только в выделенном тексте.

  `r`

    Аргумент `pattern` — регулярное выражение. Возможно использовать `\N` в `replacement` для получения энной подстроки найденного текста.

  `s`

    С учётом регистра.

  `w`

    Только целые слова.

ifind {STRING pattern}

  Поиск «по мере набора». Для настройки параметров поиска следует указать один или несколько флагов после двоеточия: `ifind:options pattern`. Допустимые параметры:

  `b`

    Искать в обратном направлении.

  `r`

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

  `s`

    С учётом регистра.

  `c`

    Искать от позиции курсора.

#### Команды базовых функций редактора (определяются приложением, в котором используется компонент редактирования)

w

  Сохранить текущий документ.

wa

  Сохранить все открытые документы.

q

  Закрыть текущий документ.

qa

  Закрыть все открытые документы.

wq

  Сохранить и закрыть текущий документ.

wqa

  Сохранить и закрыть все открытые документы.

x

  Сохранить и закрыть текущий документ только в том случае, если он был изменён.

x

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

bp

  Перейти к предыдущему документу в списке документов.

bn

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

new

  Открыть новый документ в представлении, разделённом по горизонтали.

vnew

  Открыть новый документ в представлении, разделённом по вертикали.

e

  Обновить текущий документ, если файл этого документа на диске был изменён.

enew

  Редактировать новый документ.

print

  Открыть диалог печати текущего документа.

Использование сворачивания кода
Использование сворачивания кода

## Использование сворачивания кода

Сворачивание кода позволяет скрывать участки документа в редакторе, упрощая просмотр больших документов. В KatePart разделение на сворачиваемые участки определяется правилами подсветки синтаксиса. Следовательно, оно доступно не для всех форматов файлов. В основном сворачивание кода доступно в режиме написания исходного кода, XML-разметки и тому подобного. Большинство способов подсветки позволяют также самостоятельно определять скрываемые области, чаще всего с помощью ключевых слов `BEGIN` и `END`.

Чтобы использовать функцию сворачивания, включите отображение полосы сворачивания блоков (пункт меню Вид → Полоса сворачивания блоков), если она ещё не отображается. В этой полосе, расположенной с левой стороны документа, содержится графическое представление сворачиваемых участков. Треугольник, указывающий вниз, обозначает, что участок развёрнут. Треугольник, указывающий вправо, обозначает свёрнутый участок. Щелчок по треугольнику приведёт, соответственно, к сворачиванию или разворачиванию участка (с одновременным изменением графического представления).

Для управления состоянием сворачиваемых участков доступны три команды, смотрите справку по меню.

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

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

Глава 6. Расширение функциональных возможностей KatePart
Расширение функциональных возможностей KatePart

# Глава 6. Расширение функциональных возможностей KatePart

T.C. Hollingsworth `<tchollingsworth@gmail.com>`

Перевод на русский язык: Андрей Балагута
Перевод на русский язык: Алексей Опарин
Перевод на русский язык: Олеся Герасименко

## Введение

Как и любой другой улучшенный компонент редактирования, KatePart предоставляет разнообразные возможности расширения своей функциональности Возможно создавать простые сценарии, которые реализуют дополнительные возможности, с помощью JavaScript. Расширив возможности KatePart, присоединяйтесь к нам и делитесь созданными инструментами с пользователями по всему миру!

Подсветка синтаксиса
Подсветка синтаксиса

## Подсветка синтаксиса

### Обзор

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

Функция на языке C++, показанная с подсветкой синтаксиса.

Та же самая функция на языке C++, показанная без подсветки синтаксиса.

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

KatePart содержит гибкую настраиваемую систему, которая позволяет выполнять подсветку синтаксиса. В стандартный дистрибутив входят определения для широкого диапазона языков программирования, написания сценариев и разметки, а также для других форматов текстовых файлов. Кроме того, поддерживается добавление пользовательских определений в простых файлах XML.

KatePart автоматически определяет корректные правила синтаксиса при открытии файла пользователем, основываясь на типе MIME этого файла (тип определяется по расширению файла, а если таковое отсутствует — по его содержимому). Если в результате автоматического определения выбраны не те правила синтаксиса, возможно указать их вручную с помощью меню: Сервис → Подсветка.

Стили и цвета, которые используются в определениях подсветки синтаксиса, возможно настроить на вкладке Для отдельных форматов диалога настройки, а типы MIME и расширения файлов, для которых следует использовать эти определения, — на вкладке Типы файлов.

### Примечание

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

### Система подсветки синтаксиса KatePart

В этом разделе приводится более подробное описание механизма подсветки синтаксиса, который используется в KatePart. Рекомендуется ознакомиться с этой информацией перед изменением или созданием определений синтаксиса.

#### Принцип работы подсветки синтаксиса

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

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

Определения синтаксиса, используемые системой подсветки синтаксиса KatePart, представляют собой файлы XML, которые содержат

- Правила определения роли текста, объединённые в контекстные блоки

- Списки ключевых слов

- Определения элементов стиля

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

#### Правила

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

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

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

#### Контекстные стили и ключевые слова

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

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

Во многих форматах существуют списки слов, которые соответствуют определённому элементу. Например, в языках программирования операторы управления составляют один элемент, названия типов данных — другой, встроенные функции языка — третий. Система подсветки синтаксиса KatePart поддерживает использование таких списков для выявления и обозначения слов в тексте с целью смыслового подчёркивания назначения элементов в текстовых форматах.

#### Стили по умолчанию

Если открыть в KatePart файл исходного кода на языке C++, Java™ или документ HTML, для синтаксической разметки будут использоваться одни и те же цвета (несмотря на то, что разные форматы файлов обуславливают выбор разных слов для обозначения элементов текста). Это происходит, потому что в KatePart используется предустановленный список стилей по умолчанию, которые применяются отдельными определениями синтаксиса.

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

### Подсказка

При создании всех стилей определения синтаксиса используют один из стилей по умолчанию. В некоторой части определений синтаксиса используются дополнительные стили, которых нет среди стилей по умолчанию, поэтому в случае частой работы с файлами в таких форматах целесообразно открыть диалоговое окно настройки и посмотреть, не используются для определённых элементов одинаковые стили. Например, существует только один стиль по умолчанию для строк, но, поскольку в языке программирования Perl существует два типа строк, возможно настроить подсветку для каждого из этих типов немного по-разному. Обзор всех доступных стилей по умолчанию приводится далее.

### Формат XML определения подсветки

#### Обзор

В KatePart используется библиотека подсветки синтаксических конструкций из KDE Frameworks. По умолчанию в неё включены средства подсветки кода XML.

Этот раздел посвящён обзору формата XML определения подсветки. С помощью небольшого примера в разделе описаны основные компоненты, их назначение и использование. В следующем разделе подробно рассматриваются правила определения способа подсветки.

Формальное определение (XSD) доступно в репозитории подсветки синтаксиса, в файле `language.xsd`

Пользовательские файлы `.xml` подсветки синтаксиса расположены в каталоге `org.kde.syntax-highlighting/syntax/` в папке пользователя (расположение возможно определить с помощью команды `qtpaths`--paths GenericDataLocation``, обычно это ``$HOME`/.local/share/` и `/usr/share/`).

В случае пакетов Flatpak и Snap расположение данных различается в зависимости от конкретного приложения. В приложении Flatpak расположением пользовательских файлов XML обычно является ``$HOME`/.var/app/`название-пакета-flatpak`/data/org.kde.syntax-highlighting/syntax/`, а в приложении Snap — ``$HOME`/snap/`название-пакета-snap`/current/.local/share/org.kde.syntax-highlighting/syntax/`.

В Windows® эти файлы хранятся в `%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax`. `%USERPROFILE%` обычно имеет значение `C:\Users\`пользователь``.

В целом, для большинства конфигураций каталогом пользовательских файлов XML будет:

Для локального пользователя | ``$HOME`/.local/share/org.kde.syntax-highlighting/syntax/`
Для всех пользователей | `/usr/share/org.kde.syntax-highlighting/syntax/`
Для пакетов Flatpak | ``$HOME`/.var/app/`название-пакета-flatpak`/data/org.kde.syntax-highlighting/syntax/`
Для пакетов Snap | ``$HOME`/snap/`название-пакета-snap`/current/.local/share/org.kde.syntax-highlighting/syntax/`
В Windows® | `%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax`
В macOS® | ``$HOME`/Library/Application Support/org.kde.syntax-highlighting/syntax/`

Если для одного языка имеется несколько файлов, будет загружен файл с наибольшим значением атрибута `version` в элементе `language`.

Основные разделы файлов определения синтаксиса 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>

#### Подробные сведения о разделах

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

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

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

  `attribute` определяет стиль, который следует использовать для символа, если не обнаружено соответствие ни одному из правил или если в правиле не указан атрибут. В последнем случае будет использоваться attribute контекста, указанного в context правила.

  `lineEndContext` определяет контекст, на который переключается система подсветки при достижении конца строки. Значением этого атрибута может быть либо название другого контекста, либо `#stay` для запрета смены контекста (ничего не делать), либо `#pop` для выхода из контекста. Возможно, например, указать `#pop#pop#pop`, чтобы система поднялась на три контекста выше, или даже `#pop#pop!OtherContext`, чтобы система поднялась на два контекста выше и переключилась на контекст с названием `OtherContext`. Также возможно переключиться на контекст, который принадлежит другому определению языка, так же, как в правилах `IncludeRules` (например, `SomeContext##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` определяет свойства комментариев, которые будут использованы для действий в пунктах меню Сервис → Закомментировать, Сервис → Раскомментировать и Сервис → Закомментировать или раскомментировать. Доступные атрибуты:

  `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, математический режим LATEX, ...

  `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`, если не подходит иное.

### Правила определения способа подсветки

В этом разделе приводится описание правил определения синтаксиса.

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

Правило выглядит следующим образом:

    <RuleName attribute="(идентификатор)" context="(идентификатор)" [специфичные для правила атрибуты] />

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

context возможно определить с помощью:

- идентификатора, который является названием другого контекста.

- Значение order, которое сообщает движку, что следует остаться в текущем контексте (`#stay`) или вернуться к предыдущему контексту, использованному в строке (`#pop`). Пустой или отсутствующий контекст соответствует `#stay`.

  Чтобы вернуться на несколько уровней контекста назад, ключевое слово #pop возможно повторить несколько раз: `#pop#pop#pop`

- Значение order, за которым следуют восклицательный знак (!) и значение identifier, что заставит движок сначала использовать порядок, а затем переключиться на другой контекст, например `#pop#pop!OtherContext`.

- Идентификатор, который является названием контекста, за которым следуют два символа решётки (`##`) и другой идентификатор, который является названием определения языка. Такое именование похоже на используемое в правилах `IncludeRules` и позволяет переключаться на контекст, принадлежащий другому определению подсветки синтаксиса (например, `SomeContext##JavaScript`).

Специфичные для правила атрибуты могут быть разными, их описание приводится в следующих разделах.

Общие атрибуты

Следующие атрибуты являются общими для всех правил, их возможно указывать везде, где в списке имеется надпись `(common attributes)`. Все атрибуты являются необязательными.

- attribute: атрибут, указывающий на заданный itemData. По умолчанию: attribute из контекста, указанного в атрибуте context.

- context: определяет контекст, на который следует переключить систему подсветки в случае выявления соответствия правила. По умолчанию: #stay.

- beginRegion: начать блок сворачивания кода. Значение по умолчанию: unset.

- endRegion: закрыть блок сворачивания кода. Значение по умолчанию: unset.

- lookAhead: если значение true, система подсветки не обрабатывает длину соответствия. Значение по умолчанию: false.

- firstNonSpace: соответствие устанавливается, только если строка является первой отличной от пробелов последовательностью символов в строке текста. Значение по умолчанию: false.

- column: соответствие устанавливается, если будет совпадать строка. Значение по умолчанию: unset.

Динамические правила

Некоторые из правил позволяют устанавливать необязательный атрибут `dynamic`. Это атрибут логического типа, его значение по умолчанию: false. Если атрибут dynamic имеет значение true, в правиле возможно использовать заполнители, которые обозначают текст, найденный с помощью правила регулярного выражения. Текст будет переключён в текущий контекст в его атрибутах `string` или `char`. В атрибуте `string` заполнитель `%N` (где N — это число) будет заменён соответствующим захваченным элементом `N` из вызывающего регулярного выражения, начиная с 1. В атрибуте `char` заполнитель должен быть числом `N`, он будет заменён на первый символ соответствующего захваченного элемента `N` из вызывающего регулярного выражения. Все правила, разрешающие использование этого атрибута, обозначены надписью (dynamic).

- dynamic: может иметь значение (true|false).

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

В регулярных выражениях правил `RegExpr` средство обработки захватывает и запоминает весь текст в простых круглых скобках `(ШАБЛОН)`. Захваченные фрагменты текста можно использовать в контексте, на который переключается средство, в правилах с атрибутом `dynamic` true для замены `%N` (в String) или `N` (в char).

Необходимо помнить, что фрагмент текста, захваченный в правиле `RegExpr`, сохраняется только в переключённом контексте, который указан с помощью атрибута `context` элемента.

### Подсказка

- Если захваченные фрагменты текста не будет использоваться ни динамическими правилами, ни в том же регулярном выражении, следует использовать `группы без захвата`: `(?:ШАБЛОН)`

  Захват групп с поиском вперёд или поиском назад, например `(?=ШАБЛОН)`, `(?!ШАБЛОН)` или `(?<=ШАБЛОН)`, не выполняется. Дополнительные сведения доступны в разделе Регулярные выражения.

- Группы с захватом возможно использовать внутри того же регулярного выражения, если указать `\N` вместо `%N`. Дополнительные сведения: Захват совпавшего текста (обратные ссылки) в разделе Регулярные выражения.

Пример 1:

В этом простом примере обработчик захватывает текст, соответствующий регулярному выражению `=*`, и вставляет его вместо `%1` в динамическом правиле. Это позволяет определить комментарий, который завершается тем же количеством символов `=`, что и начинается. Соответствующим текстом будет: `[[ комментарий ]]`, `[=[ комментарий ]=]` или `[=====[ комментарий ]=====]`.

Кроме того, захваченные данные доступны только в переключённом контексте Multi-line Comment.

    <context name="Normal" attribute="Normal Text" lineEndContext="#stay">
      <RegExpr context="Multi-line Comment" attribute="Comment" String="\[(=*)\[" beginRegion="RegionComment"/>
    </context>
    <context name="Multi-line Comment" attribute="Comment" lineEndContext="#stay">
      <StringDetect context="#pop" attribute="Comment" String="]%1]" dynamic="true" endRegion="RegionComment"/>
    </context>

Пример 2:

В динамическом правиле `%1` соответствует захваченному фрагменту текста, который соответствует шаблону `#+`, а `%2` — шаблону `&quot;+`. Следовательно, соответствующий фрагмент текста будет таким: `#метка""""в контексте""""#`.

Захваченными данным нельзя будет воспользоваться в других контекстах, таких как OtherContext, FindEscapes или SomeContext.

    <context name="SomeContext" attribute="Normal Text" lineEndContext="#stay">
      <RegExpr context="#pop!NamedString" attribute="String" String="(#+)(?:[\w-]|[^[:ascii:]])(&quot;+)"/>
    </context>
    <context name="NamedString" attribute="String" lineEndContext="#stay">
      <RegExpr context="#pop!OtherContext" attribute="String" String="%2(?:%1)?" dynamic="true"/>
      <DetectChar context="FindEscapes" attribute="Escape" char="\"/>
    </context>

Пример 3:

Эта запись соответствует такому тексту: `Class::function<T>( ... )`.

    <context name="Normal" attribute="Normal Text" lineEndContext="#stay">
      <RegExpr context="FunctionName" lookAhead="true"
                  String="\b([a-zA-Z_][\w-]*)(::)([a-zA-Z_][\w-]*)(?:&lt;[\w\-\s]*&gt;)?(\()"/>
    </context>
    <context name="FunctionName" attribute="Normal Text" lineEndContext="#pop">
      <StringDetect context="#stay" attribute="Class" String="%1" dynamic="true"/>
      <StringDetect context="#stay" attribute="Operator" String="%2" dynamic="true"/>
      <StringDetect context="#stay" attribute="Function" String="%3" dynamic="true"/>
      <DetectChar context="#pop" attribute="Normal Text" char="4" dynamic="true"/>
    </context>

Локальные разделители

В некоторых правилах можно воспользоваться дополнительными атрибутами `weakDeliminator` и `additionalDeliminator`, которые сочетаются с атрибутами с тем же названием тега`keywords`. Например, если `'%'` является слабым разделителем `keywords`, он может статьразделителем слов только для определённого правила, если его добавить в атрибут `additionalDeliminator` этого правила. Если правило разрешает эти атрибуты, оно содержит запись (локальные разделители).

- weakDeliminator: список символов, не являющихся разделителями слов.

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

#### Подробные сведения о правилах

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<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 (общие атрибуты) />

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

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

#### Советы и рекомендации

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

- Регулярные выражения просты в использовании, но зачастую имеются способы, позволяющие намного быстрее получить тот же результат. Предположим, требуется проверить, является ли `'#'` первым символом в строке. Соответствующее регулярное выражение выглядело бы следующим образом:

      <RegExpr attribute="Macro" context="macro" String="^\s*#" />

  Тот же результат возможно получить гораздо быстрее:

      <DetectChar attribute="Macro" context="macro" char="#" firstNonSpace="true" />

  Если требуется найти регулярное выражение `'^#'`, возможно опять же использовать `DetectChar` с атрибутом `column="0"`. Отсчёт значения атрибута `column` основан на количестве символов, следовательно, табуляция считается одним символом.

- В правилах `RegExpr` используйте атрибут `column="0"`, если будет использован шаблон `^ШАБЛОН` для установления соответствия текста в начале строки. Это ускорит обработку, так как средству обработки не потребуется выполнять поиск в остальных позициях строки.

- Используйте в регулярных выражениях группы без захвата `(?:ШАБЛОН)` вместо групп с захватом `(ШАБЛОН)`, если захваченные данные не будут использоваться в том же регулярном выражении или в динамических правилах. Это позволяет избежать ненужного хранения этих данных.

- Возможно переключать контексты без обработки символов. Предположим, что требуется переключить контекст при обнаружении строки `*/`, но при этом обработать эту строку в следующем контексте. Приведённое далее правило позволяет найти соответствие, а благодаря атрибуту `lookAhead` средство определения подсветки сохранит найденную строку для обработки в следующем контексте.

      <StringDetect attribute="Comment" context="#pop" String="*/" lookAhead="true" />

- Используйте `DetectSpaces`, если известно, что имеется несколько пробелов.

- Используйте `DetectIdentifier` вместо регулярного выражения `'[a-zA-Z_]\w*'`.

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

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

- Корректность каждого файла XML возможно проверить с помощью команды validatehl.sh mySyntax.xml. Файл `validatehl.sh` использует файл `language.xsd`, они оба доступны в репозитории подсветки синтаксиса.

- Если в файле часто используются сложные регулярные выражения, возможно воспользоваться определением ENTITIES. Пример:

      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE language
      [
              <!ENTITY myref    "[A-Za-z_:][\w.:_-]*">
      ]>

  После такого определения возможно использовать &myref; вместо регулярного выражения.

- В редакторе Kate перезагрузить синтаксис можно с помощью встроенной командной строки (по умолчанию она вызывается нажатием клавиши `F7`) и команды reload-highlighting.

- Утилита командной строки `ksyntaxhighlighter6` (в старых версиях — `kate-syntax-highlighter`) позволяет проверить синтаксис и увидеть стиль и участки, связанные с каждой из частей текста.

  Результат ksyntaxhighlighter6 --output-format=ansi --syntax-trace=format test.cpp.

  Для получения сведений о других параметрах воспользуйтесь командой ksyntaxhighlighter6 -h.

Работа с цветовыми схемами
Работа с цветовыми схемами

## Работа с цветовыми схемами

### Обзор

Цветовые схемы определяют цвета области редактирования текста и подсветку синтаксиса. Цветовая схема включает следующее:

- Стиль текста, используемый для подсветки синтаксиса через атрибуты типовых стилей. Например, цвет текста и цвет выделенного текста.

- Фон области редактирования текста, включая выделение текста и текущую строку.

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

- Декораторы текста, такие как маркеры поиска, отступов и табуляции или пробелов, обозначение парных скобок и разметка при проверке правописания.

- Закладки и фрагменты текста.

Это не касается следующих параметров интерфейса:

- Тип шрифта и размер шрифта.

- Цвета в программе редактирования текста, в частности на карте полосы прокрутки, в меню, на панели вкладок, цвет окна и так далее. В приложениях KDE, в частности Kate или KDevelop, эти цвета определяются `глобальной схемой цветов KDE Plasma`, которая указана в модуле «Цвета» программы «Параметры системы» или в самой программе, в меню Настройка → Цветовая схема.

Цветовые схемы «Breeze, светлый вариант» и «Breeze, тёмный вариант» с подсветкой синтаксиса «C++».

### Цветовые схемы KSyntaxHighlighting

KSyntaxHighlighting — это движок подсветки синтаксиса, библиотека, которая `предоставляет доступ к цветовым схемам и позволяет управлять ими`. Она является частью KDE Frameworks, её используют текстовые редакторы KDE, такие как Kate, KWrite, Kile и KDevelop. Эта зависимость выглядит следующим образом:

Зависимость от библиотек KDE Frameworks в текстовых редакторах.

KSyntaxHighlighting включает ряд встроенных схем, которые показаны на странице «цветовых схем» веб-сайта редактора Kate.

Библиотека KTextEditor, которая представляет собой движок редактирования текста, предоставляет интерфейс пользователя для создания и редактирования цветовых схем, в том числе средство импорта и экспорта схем. С помощью этого интерфейса проще всего создавать и редактировать схемы; чтобы получить доступ к нему, следует открыть диалоговое окно «Настройка» текстового редактора. Подробнее: «Графический интерфейс цветовых схем».

Графический интерфейс для управления цветовыми схемами в параметрах Kate.

Важно помнить, что в текстовых редакторах KDE, таких как Kate или KDevelop, цветовые схемы KSyntaxHighlighting используются с KDE Frameworks 5.75 (дата выхода — 10 октября 2020 года). Ранее использовались цветовые схемы Kate (настройка схемы на основеKConfig), которые теперь считаются устаревшими. Тем не менее, возможно преобразовать старые схемы Kate в цветовые схемы KSyntaxHighlighting. Репозиторий KSyntaxHighlighting содержит сценарий `utils/kateschema_to_theme_converter.py` и утилиту `utils/schema-converter/`, предназначенные для этого.

### Формат JSON цветовых схем

#### Обзор

Цветовые схемы хранятся в файлах формата JSON с расширением `.theme`.

В хранилище исходного кода KSyntaxHighlighting файлы JSON встроенных схем располагаются в каталоге `data/themes/`. Обратите внимание, что в текстовых редакторах встроенные схемы скомпилированы в библиотеку KSyntaxHighlighting.Поэтому для доступа к ним требуется исходный код или выполнение экспорта из графического интерфейса управления схемами KTextEditor.

Также возможно легко добавлять дополнительные или пользовательские схемы, которые будут загружаться из файловой системы компьютера. Пользовательские файлы схем расположены в каталоге `org.kde.syntax-highlighting/themes/` в папке пользователя (её расположение возможно определить с помощью команды `qtpaths`--paths GenericDataLocation``, обычно это ``$HOME`/.local/share/` и `/usr/share/`).

В случае пакетов Flatpak и Snap расположение данных различается в зависимости от конкретного приложения. В приложении Flatpak расположением пользовательских файлов схем обычно является ``$HOME`/.var/app/`название-пакета-flatpak`/data/org.kde.syntax-highlighting/themes/`, а в приложении Snap — ``$HOME`/snap/`название-пакета-snap`/current/.local/share/org.kde.syntax-highlighting/themes/`.

В Windows® эти файлы хранятся в `%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes`. `%USERPROFILE%` обычно имеет значение `C:\Users\`пользователь``.

В целом, для большинства конфигураций каталогом пользовательских схем будет:

Для локального пользователя | ``$HOME`/.local/share/org.kde.syntax-highlighting/themes/`
Для всех пользователей | `/usr/share/org.kde.syntax-highlighting/themes/`
Для пакетов Flatpak | ``$HOME`/.var/app/`название-пакета-flatpak`/data/org.kde.syntax-highlighting/themes/`
Для пакетов Snap | ``$HOME`/snap/`название-пакета-snap`/current/.local/share/org.kde.syntax-highlighting/themes/`
В Windows® | `%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes`
В macOS® | ``$HOME`/Library/Application Support/org.kde.syntax-highlighting/themes/`

Если имеется несколько файлов схем с одним и тем же именем, будет загружен файл с наибольшим значением атрибута `revision`.

#### Структура JSON

Описание структуры файла JSON приводится на соответствующем веб-сайте. Как правило, файл формата JSON состоит из следующих компонентов:

- Наборы разделённых запятыми пар «ключ/значение», заключённые в фигурные скобки`{ }`. Эти наборы называются «объектами».

- Упорядоченные списки разделённых запятыми значений, заключённые в квадратные скобки `[ ]`. Эти списки называются «массивами».

В этом руководстве используются термины «ключ», «значение», «объект» и «массив». Если пользователь не работал с файлами JSON ранее, понять эту терминологию помогут приведённые далее примеры.

#### Основные разделы файлов JSON цветовых схем

Корневой объект файла JSON цветовой схемы содержит следующие ключи схемы:

- `metadata`: является обязательным. Значение представляет собой объект с метаданными схемы, такими как её название, версия и условия лицензирования.

  Подробнее: «Метаданные».

- `editor-colors`: является обязательным. Значение представляет собой объект с цветами области редактирования текста, такими как цвет фона, полосы закладок и обрамления текста.

  Подробнее: «Цвета редактора».

- `text-styles`: является обязательным. Значение представляет собой объект с атрибутами типового стиля текста для подсветки синтаксиса. Каждый атрибут определяет свой цвет текста, цвет выделенного текста, а также будет ли шрифт, например, полужирным или курсивным. На стили текста возможно ссылаться из атрибутов файлов XML определения синтаксиса.

  Подробнее: «Стиль текста».

- `custom-styles`: является необязательным. Определяет стили текста для атрибутов конкретных определений подсветки синтаксиса. Например, в определении подсветки для `Python` или `Markdown` возможно указать другой стиль текста, который будет иметь приоритет над стилем по умолчанию, заданным в `text-styles`.

  Подробнее: «Для отдельных форматов».

Язык JSON не поддерживает комментарии. Тем не менее, для записи комментариев возможно использовать необязательный ключ `_comments` в корневом объекте. Например, если выполняется адаптация существующей схемы, можно добавить URL-адрес исходного репозитория. Наиболее практичным способом комментирования является использование массива строк.

Далее приводится пример для схемы «Breeze, светлый вариант». Как можно заметить, объекты `editor-colors` и `text-styles` содержат не все необходимые ключи (чтобы пример не был слишком большим). Ознакомиться со всем кодом схемы «Breeze, светлый вариант» возможно в репозитории KSyntaxHighlighting.

    {
        "_comments": [
            "This is a comment.",
            "If this theme is an adaptation of another, put the link to the original repository."
        ],
        "metadata": {
            "name" : "Breeze Light",
            "revision" : 5,
            "copyright": [
                "SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org>",
                "SPDX-FileCopyrightText: 2016 Dominik Haumann <dhaumann@kde.org>"
            ],
            "license": "SPDX-License-Identifier: MIT"
        },
        "editor-colors": {
            "BackgroundColor" : "#ffffff",
            "CodeFolding" : "#94caef",
            "BracketMatching" : "#ffff00",
            "CurrentLine" : "#f8f7f6",
            "IconBorder" : "#f0f0f0",
            "IndentationLine" : "#d2d2d2",
            "LineNumbers" : "#a0a0a0",
            "CurrentLineNumber" : "#1e1e1e",
            Другие ключи цвета редактора...

        },
        "text-styles": {
            "Normal" : {
                "text-color" : "#1f1c1b",
                "selected-text-color" : "#ffffff",
                "bold" : false,
                "italic" : false,
                "underline" : false,
                "strike-through" : false
            },
            "Keyword" : {
                "text-color" : "#1f1c1b",
                "selected-text-color" : "#ffffff",
                "bold" : true
            },
            "Function" : {
                "text-color" : "#644a9b",
                "selected-text-color" : "#452886"
            },
            "Variable" : {
                "text-color" : "#0057ae",
                "selected-text-color" : "#00316e"
            },
            Другие ключи стиля текста...

        },
        "custom-styles": {
            "ISO C++": {
                "Data Type": {
                    "bold": true,
                    "selected-text-color": "#009183",
                    "text-color": "#00b5cf"
                },
                "Keyword": {
                    "text-color": "#6431b3"
                }
            },
            "YAML": {
                "Attribute": {
                    "selected-text-color": "#00b5cf",
                    "text-color": "#00b5cf"
                }
            }
        }
    }

#### Метаданные

Объект JSON ключа `metadata` содержит соответствующую информацию о схеме. Этот объект имеет следующие ключи:

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

- `revision`: целое число, которое задаёт текущую версию файла схемы. Не забывайте увеличивать номер версии при каждом обновлении файла схемы. Этот ключ является обязательным.

- `license`: это строка, которая определяет условия лицензирования схемы с помощью идентификатора `SPDX-License-Identifier` из стандартного формата обмена условиями лицензирования SPDX. Этот ключ является необязательным.

  Полный список идентификаторов условий лицензирования SPDX доступен здесь.

- `copyright`: это массив строк, который определяет авторов схемы с помощью идентификатора `SPDX-FileCopyrightText` из стандартного формата обмена условиями лицензирования SPDX. Этот ключ является необязательным.

    "metadata": {
        "name" : "Breeze Light",
        "revision" : 5,
        "copyright": [
            "SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org>",
            "SPDX-FileCopyrightText: 2016 Dominik Haumann <dhaumann@kde.org>"
        ],
        "license": "SPDX-License-Identifier: MIT"
    }

### Подробные сведения о цветах

В этом разделе приводится описание всех доступных атрибутов цветов и доступных параметров цветов.

#### Цвета редактора

Соответствует цветам области редактирования текста.

В файле JSON схемы значением соответствующего ключа `editor-colors` являетсяобъект, в котором каждый ключ указывает цвет атрибута в текстовом редакторе. Здесь `все доступные ключи являются обязательными`. Их значения представляют собой `строки` шестнадцатеричных цветовых кодов, например «#00B5CF».

В графическом интерфейсе для управления схемами KTextEditor эти атрибуты возможно изменить на вкладке `Цвета`.

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

Область редактирования
  `BackgroundColor` (Фон)

    Цвет фона всего окна редактора, он будет подложкой под другими цветами в области редактора.

  `TextSelection` (Выделенный текст)

    Фон выделенного текста.

  `CurrentLine` (Текущая строка)

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

  `SearchHighlight` (Найденный текст)

    Цвет текста, соответствующего последнему поисковому запросу.

  `ReplaceHighlight` (Заменённый текст)

    Цвет текста, соответствующего последней операции замены.

Полоса закладок
  `IconBorder` (Фон)

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

  `LineNumbers` (Номера строк)

    Этот цвет используется для цифр номеров строк у левой границы окна редактирования.

  `CurrentLineNumber` (Номер текущей строки)

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

  `Separator` (Разделитель)

    Этот цвет используется для вертикальной линии, отделяющей полосу закладок от фона области текста.

  `WordWrapMarker` (Маркер переноса слов)

    Этот цвет используется для маркера динамически перенесённых строк. Также он используется для маркера статического переноса строк.

  `CodeFolding` (Сворачивание блоков кода)

    Цвет для выделения части кода, которая будет свёрнута при нажатии стрелки сворачивания кода в левой части окна. Более подробные сведения доступны в разделе, посвящённом сворачиванию кода.

  `ModifiedLines` (Изменённые строки)

    Цвет для выделения в левой части окна тех строк, которые были изменены, но ещё не сохранены. Подробнее: «Маркеры изменённых строк».

  `SavedLines` (Сохранённые строки)

    Цвет для выделения в левой части окна тех строк, которые были изменены в этом сеансе и сохранены. Подробнее: «Маркеры изменённых строк».

Обрамление текста
  `SpellChecking` (Подчёркивание орфографической ошибки)

    Цвет для обозначения орфографических ошибок.

  `TabMarker` (Маркеры табуляции и пробелов)

    Цвет маркеров пробелов, когда они включены.

  `IndentationLine` (Отступы)

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

  `BracketMatching` (Подсветка скобок)

    Этот цвет используется для фона парных скобок.

Маркеры
  `MarkBookmark` (Закладка)

    Цвет для обозначения закладок. Обратите внимание, что непрозрачность этого цвета составляет 22% (и 33% для текущей строки) относительно фона. Подробнее: «Использование закладок».

  `MarkBreakpointActive` (Активная точка останова)

    Цвет, который используется модулем GDB для обозначения активной точки останова. Обратите внимание, что этот цвет обладает непрозрачностью относительно фона. Более подробные сведения доступны в документации модуля GDB.

  `MarkBreakpointReached` (Текущая точка останова)

    Цвет, который используется модулем GDB для обозначения точки останова, достигнутой при отладке. Обратите внимание, что этот цвет обладает непрозрачностью относительно фона. Более подробные сведения доступны в документации модуля GDB.

  `MarkBreakpointDisabled` (Неактивная точка останова)

    Цвет, который используется модулем GDB для обозначения неактивной точки останова. Обратите внимание, что этот цвет обладает непрозрачностью относительно фона. Более подробные сведения доступны в документации модуля GDB.

  `MarkExecution` (Выполнение)

    Цвет, который используется модулем GDB для текущей исполняемой строки. Обратите внимание, что этот цвет обладает непрозрачностью относительно фона. Более подробные сведения доступны в документации модуля GDB.

  `MarkWarning` (Предупреждение)

    Цвет, который используется модулем сборки для обозначения строки, в отношении которой от компилятора было получено предупреждение. Обратите внимание, что этот цвет обладает непрозрачностью относительно фона. Более подробные сведения доступны в документации модуля сборки.

  `MarkError` (Ошибка)

    Цвет, который используется модулем сборки для обозначения строки, в отношении которой от компилятора было получено сообщение об ошибке. Обратите внимание, что этот цвет обладает непрозрачностью относительно фона. Более подробные сведения доступны в документации модуля сборки.

Шаблоны и фрагменты текста
  `TemplateBackground` (Фон)

    Цвет, который используется модулем фрагментов Kate для фона фрагмента. Более подробные сведения доступны в документации модуля фрагментов Kate.

  `TemplatePlaceholder` (Редактируемый местозаполнитель)

    Цвет, который используется модулем фрагментов Kate для обозначения местозаполнителя, который возможно нажать для редактирования вручную. Более подробные сведения доступны в документации модуля фрагментов Kate.

  `TemplateFocusedPlaceholder` (Текущий редактируемый местозаполнитель)

    Цвет, который используется модулем фрагментов Kate для обозначения местозаполнителя, который редактируется в текущий момент. Более подробные сведения доступны в документации модуля фрагментов Kate.

  `TemplateReadOnlyPlaceholder` (Нередактируемый местозаполнитель)

    Цвет, который используется модулем фрагментов Kate для обозначения местозаполнителя, который недоступен для редактирования вручную (например, местозаполнителя, который заполняется автоматически). Более подробные сведения доступны в документации модуля фрагментов Kate.

#### Стиль текста

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

### Примечание

На эти стили можно ссылаться в `типовых стилях`,которые используются в файлах XML определений подсветки синтаксиса. Например, атрибут «Normal»является эквивалентным атрибуту «dsNormal» в файлах XML, а«DataType» является эквивалентным «dsDataType». Смотритераздел «Доступные стили по умолчанию» в документации поподсветке синтаксиса.

### Подсказка

Следует выбирать хорошо читаемые цвета с достаточной контрастностью, особеннов сочетании с `цветами редактора`. Смотрите раздел «Контраст цветов текста».

В файле JSON значением соответствующего ключа`text-styles` является объект, каждый ключ которого соответствует названию типового стилятекста. Ключи являются эквивалентами ключей, которые используются вопределениях подсветки синтаксиса. Здесь `все доступные ключистиля текста обязательны`. Список ключей приведён далее.

    "text-styles": {
        "Normal" : {
            "text-color" : "#1f1c1b",
            "selected-text-color" : "#ffffff",
            "bold" : false,
            "italic" : false,
            "underline" : false,
            "strike-through" : false
        },
        "Keyword" : {
            "text-color" : "#1f1c1b",
            "selected-text-color" : "#ffffff",
            "bold" : true
        },
        "Function" : {
            "text-color" : "#644a9b",
            "selected-text-color" : "#452886"
        },
        Другие ключи стиля текста...
    }

Значением каждого ключа типового стиля текста является объект JSON, в котором указаны такие значения, как color, bold, italic и так далее. Вот эти ключи:

  `text-color`: строка с шестнадцатеричным цветовым кодом. Эта пара «ключ/значение» обязательна.

  `selected-text-color`: цвет выбранного текста. Обычно то же значение, что и «text-color». Еслитекст выбран, фон определяется значением TextSelection в цветах редактора, поэтому следует обеспечить хорошуюконтрастность текста и его читаемость на фоне. Значением является строка с шестнадцатеричным цветовым кодом. Эта пара «ключ/значение» являетсяобязательной.

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

  `italic`: логическое значение, которое определяет, является ли текст курсивным. Это необязательный ключ, значение по умолчанию — `false`.

  `underline`: логическое значение, которое определяет, является ли текст подчёркнутым. Это необязательный ключ, значение по умолчанию — `false`.

  `strike-through`: логическое значение, которое определяет, является ли текст перечёркнутым. Это необязательный ключ, значение по умолчанию — `false`.

  `background-color`: определяет фон текста, используемый, например, в комментариях. Значением является строка с шестнадцатеричным цветовым кодом. Это необязательный ключ, по умолчанию фона нет.

  `selected-background-color`: определяет фон выбранного текста. Значением является строка с шестнадцатеричным цветовым кодом. Это необязательный ключ, по умолчанию фона нет.

В графическом интерфейсе управления схемами цветов KTextEditor эти атрибуты можно изменить на вкладке `Стиль текста`. Для названия в списке стилей используется стиль для соответствующей записи. Это позволяет сразу увидеть результат применения стиля. В каждом стиле возможно выбрать общие атрибуты, а также цвета текста и фона. Чтобы сбросить цвет фона, щёлкните правой кнопкой мыши и воспользуйтесь контекстным меню.

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

Обычный текст и исходный код

  `Normal` (Обычный текст): типовой стиль текста для обычного текста и исходного кода без специальной подсветки.

  `Keyword` (Ключевое слово): стиль текста для встроенных ключевых слов языка.

  `Function` (Функция): стиль текста для определений функций и вызовов функций.

  `Variable` (Переменая): стиль текста для переменных, если таковой применим. Например, переменные в PHP/Perl обычно начинаются с символа `$`, поэтому все идентификаторы, которые соответствуют шаблону `$foo`, подсвечиваются как переменные.

  `ControlFlow` (Управляющая конструкция): стиль текста для ключевых слов управляющей конструкции, таких как if, then, else, return, switch, break, yield, continue и так далее.

  `Operator` (Операция): стиль текста для операторов, таких как `+`, `-`, `*`, `/`, `%` и так далее.

  `BuiltIn` (Встроенная функция): стиль текста для встроенных классов, функций и объектов языка.

  `Extension` (Расширение языка): стиль текста для известных расширений, таких как классы Qt™, функции и макросы в C++ и Python или boost.

  `Preprocessor` (Команды препроцессора):стиль текста для инструкций препроцессора и определений макросов.

  `Attribute` (Атрибут): стиль текста для аннотаций или атрибутов функций или объектов (например, `@override` в Java или`__declspec(...)` и `__attribute__((...))` в C++).

Числа, типы и константы

  `DataType` (Тип данных): стиль текста для встроенных типов данных, таких как int, char, float, void, u64 и так далее.

  `DecVal` (Десятичное число): стиль текста для десятичных значений.

  `BaseN` (Целое по основанию N): стиль текста для чисел с основанием, отличным от 10.

  `Float` (Число с плавающей точкой): стиль текста для чисел с плавающей точкой.

  `Constant` (Константа): стиль текста для констант языка программирования и заданных пользователем констант (например, True, False, None в Python или nullptr в C/C++, или математические константы наподобие PI).

Строки и символы

  `Char` (Символ): стиль текста для отдельных символов, таких как `'x'`.

  `SpecialChar` (Специальный символ): стиль текста для экранированных символов в строках, например«`hello\n`» и других символов со специальным значением в строках, в том числе символов-заменителей и операторов регулярных выражений.

  `String` (Строка): стиль текста для строк наподобие «`hello world`».

  `VerbatimString` (Текстовая строка): стиль текста для буквальных или необработанных строк, в частности `'raw \backlash'` в Perl, CoffeeScript и командных оболочках, а также `r'\raw'` в Python или строк, подобных here-документам.

  `SpecialString` (Специальная строка): стиль текста для специальных строк, таких как регулярные выражения в ECMAScript, код в уравнениях LATEX, код SQL и так далее.

  `Import` (Импорт, подключение модуля, включение): стиль текста для включений, импорта, модулей или пакетов LATEX.

Комментарии и документация

  `Comment` (Комментарий): стиль текста для обычных комментариев.

  `Documentation` (Документация): стиль текста для комментариев, которые отражают документацию API (например, `/** комментариев doxygen */` или `"""строк_документации"""`).

  `Annotation` (Аннотация): стиль текста для аннотаций в комментариях или командах документации (например, `@param` в Doxygen или JavaDoc).

  `CommentVar` (Переменная в комментарии): стиль текста для названий переменных в приведённых выше командах в комментарии (например, `foobar` в «`@param foobar`» для кода Doxygen или JavaDoc).

  `RegionMarker` (Маркер блока): стиль текста для маркеров блока, который обычно определяется `//BEGIN` и `//END` в комментариях.

  `Information` (Информационное сообщение): стиль текста для информационных сообщений, заметок и советов (например, ключевого слова `@note` в Doxygen).

  `Warning` (Предупреждение): стиль текста для предупреждений (например, ключевого слова `@warning` в Doxygen).

  `Alert` (Серьёзное предупреждение): стиль текста для специальных слов в комментариях, таких как `TODO`, `FIXME`, `XXXX` и `WARNING`.

Разное

  `Error` (Ошибка): стиль текста для обозначения подсветки ошибок и неверного синтаксиса.

  `Others` (Другое): стиль текста для атрибутов, которые не соответствуют ни одному из других типовых стилей.

#### Для отдельных форматов

Здесь возможно установить стили текста для конкретного определения синтаксиса, переопределив `типовой стиль текста`, который описан в предыдущемразделе.

В файле JSON схемы этот ключ соответствует ключу `custom-styles`, значением которого является объект, каждый ключ подчинённой схемы которого соответствует `названию определения подсветки синтаксиса`. Его значением является объект, каждый ключ которого соответствует`названию атрибутов стиля`, определённому в элементах `itemData`файла XML подсветки синтаксиса, и соответствующее значение является подчинённым объектом с ключами text-color, selected-text-color, bold, italic,underline, strike-through,background-color и selected-background-color, определённым в предыдущем разделе. Все эти значения необязательны, поскольку, если они не указаны, будет использован стиль, определённый в `text-styles`.

Например, в этом фрагменте кода определение подсветки синтаксиса «ISO C++» содержит специальный стиль текста для атрибутов «Type Modifiers» и «Standard Classes». В соответствующем файле XML «isocpp.xml» для определённого атрибута «Standard Classes» используется типовой стиль `BuiltIn` (или dsBuiltIn). В этом атрибуте будет перезаписано только значение `text-color` — новым цветом «#6431b3».

    "custom-styles": {
        "ISO C++": {
            "Standard Classes": {
                "text-color": "#6431b3"
            },
            "Type Modifiers": {
                "bold": true,
                "selected-text-color": "#009183",
                "text-color": "#00b5cf"
            }
        }
    }

### Примечание

- Следует учитывать, что эти стили текста связаны с названиями атрибутов в файлах XML подсветки синтаксиса. Если файл XML будет обновлён и некоторые атрибуты будут переименованы или удалены, нестандартный стиль, определённый в этой схеме, станет неприменимым.

- Определения подсветки синтаксических конструкций часто включают другие определения. Например, определение подсветки «QML» включает определение подсветки «JavaScript», поскольку они содержатобщие функциональные возможности подсветки.

В графическом интерфейсе управления схемами KTextEditor эти атрибуты можно изменить на вкладке`Для отдельных форматов`. Обычно редактор предварительно выбирает подсветку для текущего документа. Многие определения подсветок содержат другие определения подсветок, обозначаемые группами в списке стилей. Например, большинство определений подсветок импортируют подсветку «Alert», а многие форматы исходного кода импортируютподсветку «Doxygen».

### Графический интерфейс цветовых схем

Проще всего создавать и редактировать цветовые схемы с помощью графического интерфейса — диалогового окна «Настройка» KTextEditor. Чтобы открыть это окно, выберите в меню текстового редактора пункт Настройка → Настроить `имя_программы`.... В открывшемся окне Настройка следует выбрать расположенный на боковой панели пункт Цветовые схемы.

Диалог настройки Kate с параметрами цветовой схемы.

В этом диалоге возможно настроить все цвета любой схемы, а также создать или скопировать схему, удалить её, экспортировать в файл `.theme` в формате JSON или импортировать из внешнего файла `.theme`. В каждой схеме предусмотрены параметры для цветов и стилей текста.

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

Чтобы установить схему для постоянного использования в текстовом редакторе, необходимо выбрать её с помощью расположенного в нижней части окна раскрывающегося списка Схема по умолчанию для `имя_программы` и нажать кнопку Применить или ОК. По умолчанию активен вариант`Автоматический выбор`. Использование этого варианта приводит к выбору цветовой схемы, которая лучше подходит к цветовой схеме KDE Plasma для редактирования текста.Обычно выбор осуществляется между «Breeze, светлый вариант» и «Breeze, тёмный вариант». Выбор зависит от того, какой является схема среды — светлой или тёмной.

### Подсказка

Глобальную цветовую схему KDE возможно настроить в модуле «Цвета» приложения «Параметры системы». Также возможно сменить её в некоторых программах, таких как Kate или KDevelop, с помощью пункта меню Настройка → Цветовая схема.

#### Создание новой схемы

Чтобы создать новую схему, необходимо сначала скопировать существующую. Выберите существующую схему, которую следует использовать в качестве основы (например, «Breeze, светлый вариант» или «Breeze, тёмный вариант»), и нажмите кнопку Копировать…. Затем укажите название новой схемы.

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

#### Импорт или экспорт файлов схем JSON

Выбранную тему (включая встроенные) возможно экспортировать в файл JSON с расширением `.theme` путём нажатия кнопки Экспорт. Будет открыт диалог сохранения файла. Чтобы добавить цветовую схему из внешнего файла JSON, просто нажмите кнопку Импорт и выберите в диалоге файл `.theme`.

### Подсказка

- Как уже упоминалось выше, настроенные пользователями схемы хранятся в каталоге `org.kde.syntax-highlighting/themes/`. Когда тема копируется или создаётся, она автоматически появляется там.Кроме того, импорт или добавление темы эквивалентны копированию внешнего файла `.theme` в этот каталог. KSyntaxHighlighting автоматически выбирает файлы цветовых схем из указанного каталога.

- Перед публикацией созданной темы необходимо проверить корректность объектаmetadata в файле JSON, добавив в него соответствующие условия лицензирования и указав номер версии.

#### Редактирование цветовых схем

##### Цвета

Здесь настраиваются цвета области редактирования текста. Подробное описание параметров приводится в разделе «Цвета редактора».

##### Стиль текста

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

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

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

Подробное описание атрибутов этой области приводится в разделе «Стиль текста».

##### Для отдельных форматов

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

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

Для каждого стиля возможно выбрать общие атрибуты, а также цвета текста и фона. Чтобы отменить установку цвета фона, щёлкните правой кнопкой мыши для вызова контекстного меню. Кроме того, можно посмотреть, совпадает стиль с типовым стилем, который используется для элемента, и установить его в случае несовпадения.

Обратите внимание, многие подсветки содержат другие подсветки, представленные группами в списке стилей. Например, многие подсветки импортируют подсветку «Alert», а многие форматы исходного кода — подсветку «Doxygen». Изменение цветов в таких группах влияет на стили только при использовании в редактируемом формате подсветки.

### Советы и рекомендации

#### Контраст цветов текста

Важным аспектом работы с цветовыми схемами является выбор контрастного цветатекста, который упростит чтение, особенно в сочетании с цветом фона.

Приложение `Kontrast` предназначено для проверки контрастности цветов. Эта программа позволяет проверить, является ли сочетание цвета текста и цвета фона хорошо читаемым, что облегчает создание цветовых схем.

Программу `Kontrast` возможно загрузить на веб-сайте приложений KDE или установить из пакета Flatpak на Flathub (только в GNU/Linux).

Приложение GNOME `Contrast` работает аналогичным образом. Возможно загрузить пакет Flatpak на Flathub (только в GNU/Linux).

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

#### Предложения по согласованности подсветки синтаксиса

KSyntaxHighlighting включает более 300 определений подсветки синтаксиса; желательно убедиться, что новая схема выглядит хорошо во всех определениях подсветки синтаксиса. Во встроенных цветовых темах использованы следующие принципы, которыми рекомендуется (но не обязательно) пользоваться для корректного отображения всех определений подсветки синтаксиса:

- Использовать полужирный шрифт для стилей текста «Keyword» and «ControlFlow».

- Не использовать цвет фона в стилях текста, за исключением «Alert» и «RegionMarker».

Большинство подсветок синтаксиса хорошо выглядят в типовых схемах «Breeze, светлый вариант» и «Breeze, тёмный вариант». Следовательно, ещё одним способом обеспечения согласованности является использование похожих цветов в стилях текста. Например, зелёного для «Preprocessor» и «Others», синего для «DataType» и «Attribute» или фиолетового для «Function».

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

Написание сценариев JavaScript
Написание сценариев JavaScript

## Написание сценариев JavaScript

Функциональность компонента редактирования KatePart возможно расширить с помощью написания сценариев. Для этого используется язык ECMAScript (широко известен как JavaScript). KatePart поддерживает два вида сценариев: сценарии расстановки отступов и сценарии командной строки. Функциональные возможности, похожие на сценарии командной строки, также доступны в подключаемом модуле фрагментов.

### Сценарии расстановки отступов

Сценарии расстановки отступов — также их называют средствами расстановки отступов — выполняют автоматическую расстановку отступов в исходном коде по мере набора текста. Например, после нажатия клавиши Enter программа обычно увеличивает отступ в следующей строке.

В следующих разделах приведены пошаговые инструкции по созданию основы простого средства расстановки отступов. На первом этапе следует создать файл `*.js` с названием, например, `javascript.js` в локальной домашней папке `$`XDG_DATA_HOME`/katepart5/script/indentation`. Здесь переменная среды `XDG_DATA_HOME` обычно имеет значение `~/.local` или `~/.local/share`.

В Windows® эти файлы расположены в каталоге `%USERPROFILE%\AppData\Local\katepart5\script\indentation`. `%USERPROFILE%` обычно имеет значение `C:\\Users\\`пользователь``.

#### Заголовок сценария расстановки отступов

Заголовок файла `javascript.js` внедряется как JSON в начало документа и имеет следующую форму:

    var katescript = {
        "name": "JavaScript",
        "author": "Example Name <example.name@some.address.org>",
        "license": "BSD License",
        "revision": 1,
        "kate-version": "5.1",
        "required-syntax-style": "javascript",
        "indent-languages": ["javascript"],
        "priority": 0,
    }; // kate-script-header, must be at the start of the file without comments

Далее приводится подробное описание каждой из записей заголовка:

- `name` [обязательная запись]: название средства расстановки отступов, которое будет показано в меню Сервис → Расстановка отступов и диалоге настройки.

- `author` [необязательная запись]: имя и контактные данные автора.

- `license` [необязательная запись]: краткая форма условий лицензирования, например BSD или LGPLv3.

- `revision` [обязательная запись]: версия сценария. Не забывайте увеличивать номер версии при каждом внесении изменений в файл.

- `kate-version` [обязательная запись]: минимальное значение версии KatePart, необходимой для работы сценария.

- `required-syntax-style` [необязательная запись]: нужный стиль синтаксиса, который соответствует указанному значению `style` в файлах определения подсветки синтаксических конструкций. Эта запись важна для средств расстановки отступов, которые работают на основе определённых данных о подсветке в документе. Если указан стиль синтаксиса, средством расстановки отступов будет возможно воспользоваться только в том случае, если будет задействовано соответствующее средство подсветки текста. Это позволяет предотвратить «неопределённое поведение», вызванное использованием средства расстановки отступов без необходимой для его работы схемы подсветки. Например, таким образом настроено средство расстановки отступов в файлах `ruby.js` и `ruby.xml`.

- `indent-languages` [необязательная запись]: массив JSON стилей синтаксических конструкций, которые может обрабатывать средство расстановки отступов, например: `["c++", "java"]`.

- `priority` [необязательная запись]: если какому-либо файлу с определённой подсветкой соответствуют несколько средств расстановки отступов, значение приоритета определяет, какое средство расстановки отступов будет использоваться по умолчанию.

#### Исходный код средства расстановки отступов

Выше был рассмотрен формате заголовка. Теперь возможно перейти к изучению того, как же работает сам сценарий расстановки отступов. Основа подобного сценария выглядит так:

    // необходимые библиотеки JS katepart, например range.js, если используется Range
    require ("range.js");

    triggerCharacters = "{}/:;";
    function indent(line, indentWidth, ch)
    {
        // сценарий будет вызываться при обработке каждого символа новой строки (ch == '\n') и всех символов, указанных в
        // глобальной переменной triggerCharacters. При выборе пункта меню Сервис → Форматированный отступ
        // переменная ch будет иметь пустое значение, то есть ch == ''.
        //
        // смотрите также раздел: «Программный интерфейс (API) работы со сценариями»
        return -2;
    }

В функции `indent()` предусмотрено три параметра:

- `line`: строка, в которой следует установить отступ

- `indentWidth`: ширина отступа (в пробелах)

- `ch`: символ новой строки (`ch == '\n'`), символ переключения, указанный в `triggerCharacters`, или пустая строка, если пользователем был выбран пункт меню Сервис → Форматированный отступ.

Значение, возвращённое функцией `indent()`, определяет способ установки отступа в строке. Если возвращённое функцией значение является простым целым числом, оно обрабатывается следующим образом:

- возвращено значение `-2`: ничего не делать

- возвращено значение `-1`: сохранить отступ (он будет определён на основе предыдущей непустой строки)

- возвращено значение `0`: числа >= 0 определяют глубину отступа в пробелах

Либо может быть возвращён массив из двух элементов:

- `возвращено [ отступ, выравнивание ];`

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

Рассмотрим следующий пример: предположим, что для создания отступов используются символы табуляции и значение ширины табуляции равняется 4. Здесь <tab> — символ табуляции, а '.' — пробел:

    1: <tab><tab>foobar("привет",
    2: <tab><tab>......."мир");

При создании отступа для строки 2 функция `indent()` возвращает [8, 15]. В результате два символа табуляции будут вставлены для создания отступа в столбце 8, а затем будет добавлено 7 пробелов для выравнивания по второму параметру, следовательно, строка останется выровненной во время просмотра файла при любой ширине табуляции.

По умолчанию в пакете KatePart KDE поставляются несколько средств расстановки отступов. Код этих средств на языке JavaScript расположен в каталоге `$`XDG_DATA_DIRS`/katepart5/script/indentation`.

В Windows® эти файлы расположены в каталоге `%USERPROFILE%\AppData\Local\katepart5\script\indentation`. `%USERPROFILE%` обычно имеет значение `C:\\Users\\`пользователь``.

При разработке средства расстановки отступов сценарии требуется перезагружать для проверки корректности поведения во время установки отступов. Вместо перезапуска приложения достаточно просто перейти в командную строку и выполнить команду reload-scripts.

Чтобы поделиться созданным полезным сценарием с разработчиками KatePart, отправьте запрос на слияние изменений в соответствующий проект на GitLab.

### Сценарии командной строки

### Примечание

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

Поскольку у всех пользователей разные потребности, в KatePart предусмотрена поддержка небольших вспомогательных инструментов для ускорения работы с фрагментами текста с помощью встроенной командной строки. Например, команда sort (упорядочить) реализована именно с помощью такого инструмента. В этом разделе содержится описание способа создания файлов `*.js`, которые позволят расширить возможности KatePart путём добавления вспомогательных сценариев.

Сценарии командной строки расположены в той же папке, что и сценарии расстановки отступов. Поэтому на первом этапе следует создать файл `*.js` с именем `myutils.js` в локальной домашней папке `$`XDG_DATA_HOME`/katepart5/script/commands`. Здесь переменная среды `XDG_DATA_HOME` обычно имеет значение `~/.local` или `~/.local/share`.

В Windows® эти файлы расположены в каталоге `%USERPROFILE%\AppData\Local\katepart5\script\commands`. `%USERPROFILE%` обычно имеет значение `C:\\Users\\`пользователь``.

#### Заголовок сценария командной строки

Заголовок каждого сценария командной строки встраивается в JSON в начале сценария следующим образом:

    var katescript = {
        "author": "Example Name <example.name@some.address.org>",
        "license": "LGPLv2+",
        "revision": 1,
        "kate-version": "5.1",
        "functions": ["sort", "moveLinesDown"],
        "actions": [
            {   "function": "sort",
                "name": "Sort Selected Text",
                "category": "Editing",
                "interactive": "false"
            },
            {   "function": "moveLinesDown",
                "name": "Move Lines Down",
                "category": "Editing",
                "shortcut": "Ctrl+Shift+Down",
                "interactive": "false"
            }
        ]
    }; // kate-script-header, must be at the start of the file without comments

Далее приводится подробное описание каждой из записей заголовка:

- `author` [необязательная запись]: имя и контактные данные автора.

- `license` [необязательная запись]: краткая форма условий лицензирования, например BSD или LGPLv2.

- `revision` [обязательная запись]: версия сценария. Не забывайте увеличивать номер версии при каждом внесении изменений в файл.

- `kate-version` [обязательная запись]: минимальное значение версии KatePart, необходимой для работы сценария.

- `functions` [обязательная запись]: массив JSON команд сценария.

- `actions` [необязательная запись]: массив JSON объектов JSON, определяющий действия, которые будут доступны в меню приложения. Подробные сведения доступны в разделе Привязки клавиш.

Так как значением `functions` является массив JSON, отдельный сценарий может содержать произвольное количество команд командной строки. Доступ к каждой из функций возможно получить с помощью встроенной командной строки KatePart.

#### Исходный код сценария

Все функции, указанные в заголовке, должны быть реализованы в сценарии. Таким образом, файл сценария из вышеприведённого примера должен реализовывать две функции: sort и moveLinesDown. Все функции должны быть записаны в следующем виде:

    // необходимые библиотеки JS katepart, например range.js, если используется Range
    require ("range.js");

    function <name>(параметр1, параметр2, ...)
    {
        // ... реализация, смотрите также раздел: «Программный интерфейс (API) работы со сценариями»
    }

Параметры в командной строке передаются функции как `параметр1`, `параметр2` и так далее. Чтобы документировать каждую команду, просто реализуйте функцию '`help`' следующим образом:

    function help(cmd)
    {
        if (cmd == "sort") {
            return i18n("Sort the selected text.");
        } else if (cmd == "...") {
            // ...
        }
    }

После этого выполнение команды help sort приведёт к вызову соответствующей функции справки (help) с параметром `cmd` в значении названия указанной команды, то есть `cmd == "sort"`. В ответ на команду в KatePart будет показан заданный текст справки. Обязательно выполните перевод строк.

При разработке сценария командной строки этот сценарий требуется перезагружать для проверки корректности поведения. Вместо перезапуска приложения достаточно просто перейти в командную строку и выполнить команду reload-scripts.

##### Привязки клавиш

Чтобы доступ к сценарию было возможно осуществлять с помощью меню приложения и с помощью комбинаций клавиш, он должен содержать соответствующий заголовок. В приведённом выше примере обе функции — `sort` и `moveLinesDown` — отображаются как соответствующие пункты меню благодаря этой части заголовка сценария:

    var katescript = {
        ...
        "actions": [
            {   "function": "sort",
                "name": "Sort Selected Text",
                "icon": "",
                "category": "Editing",
                "interactive": "false"
            },
            {   "function": "moveLinesDown",
                "name": "Move Lines Down",
                "icon": "",
                "category": "Editing",
                "shortcut": "Ctrl+Shift+Down",
                "interactive": "false"
            }
        ]
    };

Поля для одного действия таковы:

- `function` [обязательная запись]: функция, пункт которой должен отображаться в меню Сервис → Сценарии.

- `name` [обязательная запись]: текст пункта, который показан в меню сценариев.

- `icon` [необязательная запись]: значок, который отображается рядом с текстом в меню. Возможно указать название одного из значков KDE.

- `category` [необязательная запись]: если указана категория, сценарий будет отображаться в соответствующем вложенном меню.

- `shortcut` [необязательная запись]: здесь указывается комбинация клавиш, которая будет использоваться по умолчанию. Например: `Ctrl+Alt+t`. Дополнительные сведения доступны в документации Qt™.

- `interactive` [необязательная запись]: если для работы сценария требуются введённые пользователем данные, установите этот параметр в значение `true`.

Чтобы поделиться созданным полезным сценарием с разработчиками KatePart, отправьте запрос на слияние изменений в соответствующий проект на GitLab.

### Программный интерфейс (API) работы со сценариями

Программный интерфейс работы со сценариями, основы которого представлены здесь, возможно использовать для любых сценариев, в том числе сценариев расстановки отступов и сценариев командной строки. Классы `Cursor` и `Range` определяются библиотечными файлами в `$`XDG_DATA_DIRS`/katepart5/libraries`. Если требуется воспользоваться ими в определённом сценарии, чтобы задействовать какие-либо функции `Document` или `View`, включите в сценарий необходимую библиотеку с помощью следующей команды:

    // необходимые библиотеки JS katepart, например range.js, если используется Range
    require ("range.js");

Чтобы расширить стандартный программный интерфейс (API) работы со сценариями собственными функциями и прототипами, просто создайте файл в локальной папке файлов настройки KDE `$`XDG_DATA_HOME`/katepart5/libraries` и включите его в файл сценария с помощью следующего кода:

    require ("myscriptnamehere.js");

В Windows® эти файлы расположены в каталоге `%USERPROFILE%\AppData\Local\katepart5\libraries`. `%USERPROFILE%` обычно имеет значение `C:\\Users\\`пользователь``.

Рекомендованным способом расширения возможностей существующих прототипов, например `Cursor` или `Range`, не является внесение изменений в глобальные файлы `*.js`. Вместо этого следует изменить прототип `Cursor` в JavaScript после включения `cursor.js` в сценарий с помощью команды `require`.

#### Курсоры и диапазоны

Поскольку KatePart является текстовым редактором, весь программный интерфейс по возможности основан на курсорах и диапазонах текста. Объект «Cursor» (курсор) является простым кортежем `(line, column)` (строка, столбец), который определяет позицию в тексте документа. Объект «Range» (диапазон) — это фрагмент текста от начальной до конечной позиции курсора. Подробное описание программного интерфейса приводится в следующих разделах.

##### Прототип Cursor (курсор)

    Cursor();

  Конструктор. Возвращает объект «Cursor» (курсор) в позиции `(0, 0)`.

  Пример: `var cursor = new Cursor();`

    Cursor(int строка, int столбец);

  Конструктор. Возвращает объект «Cursor» (курсор) в позиции (строка, столбец).

  Пример: `var cursor = new Cursor(3, 42);`

    Cursor(Cursor другой);

  Конструктор копирования. Возвращает копию курсора `другой`.

  Пример: `var copy = new Cursor(другой);`

    Cursor Cursor.clone();

  Возвращает клон курсора.

  Пример: `var clone = cursor.clone();`

    Cursor.setPosition(int строка, int столбец);

  Устанавливает курсор в место, указанное параметрами `строка` и `столбец`.

  Начиная с KDE 4.11

    bool Cursor.isValid();

  Проверка корректности курсора. Курсор является некорректным, если строка и/или столбец установлены в значение `-1`.

  Пример: `var valid = cursor.isValid();`

    Cursor Cursor.invalid();

  Возвращает новый некорректный курсор, размещённый в позиции `(-1, -1)`.

  Пример: `var invalidCursor = cursor.invalid();`

    int Cursor.compareTo(Cursor другой);

  Сравнивает текущий курсор с курсором `другой`. Возвращает

  - `-1`, если текущий курсор расположен перед курсором `другой`

  - `0`, если курсоры находятся в одинаковых позициях

  - `+1`, если текущий курсор расположен после курсора `другой`

    bool Cursor.equals(Cursor другой);

  Возвращает `true`, если текущий курсор и курсор `другой` находятся в одинаковых позициях, в ином случае — `false`.

    String Cursor.toString();

  Возвращает курсор как строку вида «`Cursor(строка, столбец)`».

##### Прототип Range (диапазон)

    Range();

  Конструктор. Вызов `new Range()` возвращает диапазон в позиции (0, 0) - (0, 0).

    Range(Cursor начало, Cursor конец);

  Конструктор. Вызов `new Range(`начало`, `конец`)` возвращает диапазон (`начало`, `конец`).

    Range(int начальнаяСтрока, int начальныйСтолбец, int конечнаяСтрока, int конечныйСтолбец);

  Конструктор. Вызов `new Range(`начальнаяСтрока`, `начальныйСтолбец`, `конечнаяСтрока`, `конечныйСтолбец`)` возвращает диапазон с позиции (`начальнаяСтрока`, `начальныйСтолбец`) до позиции (`конечнаяСтрока`, `конечныйСтолбец`).

    Range(Range другой);

  Конструктор копирования. Возвращает копию диапазона `другой`.

    Range Range.clone();

  Возвращает клон диапазона.

  Пример: `var clone = range.clone();`

    bool Range.isEmpty();

  Возвращает `true`, если начальная и конечная позиции курсора совпадают.

  Пример: `var empty = range.isEmpty();`

  Начиная с KDE 4.11

    bool Range.isValid();

  Возвращает `true`, если начальная и конечная позиции курсора являются корректными, в ином случае — `false`.

  Пример: `var valid = range.isValid();`

    Range Range.invalid();

  Возвращает диапазон от (-1, -1) до (-1, -1).

    bool Range.contains(Cursor курсор);

  Возвращает `true`, если позиция курсора находится в этом диапазоне, в ином случае — `false`.

    bool Range.contains(Range другой);

  Возвращает `true`, если текущий диапазон содержит диапазон `другой`, в ином случае — `false`.

    bool Range.containsColumn(int столбец);

  Возвращает `true`, если `столбец` принадлежит полуоткрытому интервалу `[начальный.столбец, конечный.столбец)`, в ином случае — `false`.

    bool Range.containsLine(int строка);

  Возвращает `true`, если `строка` принадлежит полуоткрытому интервалу `[начальная.строка, конечная.строка)`, в ином случае — `false`.

    bool Range.overlaps(Range другой);

  Возвращает `true`, если текущий диапазон и диапазон `другой` имеют ненулевое пересечение, в ином случае — `false`.

    bool Range.overlapsLine(int строка);

  Возвращает `true`, если `строка` принадлежит интервалу `[начальная.строка, конечная.строка]`, в ином случае — `false`.

    bool Range.overlapsColumn(int столбец);

  Возвращает `true`, если `столбец` принадлежит интервалу `[начальный.столбец, конечный.столбец]`, в ином случае — `false`.

    bool Range.onSingleLine();

  Возвращает `true`, если диапазон начинается и заканчивается в одной и той же строке, то есть если `Range.начальная.строка == Range.конечная.строка`.

  Начиная с KDE 4.9

    bool Range.equals(Range другой);

  Возвращает `true`, если текущий диапазон и диапазон `другой` совпадают, в ином случае — `false`.

    String Range.toString();

  Возвращает диапазон как строку вида «`Range(Cursor(строка, столбец), Cursor(строка, столбец))`».

#### Глобальные функции

В этом разделе перечислены все глобальные функции.

##### Чтение и включение файлов

    String read(String название файла);

  Найти указанный `файл` в каталоге `katepart5/script/files` и вернуть его содержимое в виде строки.

    void require(String название файла);

  Найти указанный `файл` в каталоге `katepart5/script/libraries` и обработать его код. В `require` предусмотрена встроенная защита от повторного включения одного и того же `файла`.

  Начиная с KDE 4.10

##### Отладка

    void debug(String текст);

  Вывести `текст` в `stdout` в консоль, с помощью которой запущено приложение.

##### Перевод

Полноценная локализация станет возможной только при использовании нескольких функций, предназначенных для перевода строк, а именно: `i18n`, `i18nc`, `i18np` и `i18ncp`. Поведение этих функций в точности соответствует поведению функций перевода строк KDE.

С помощью функций перевода и системы перевода KDE встроенные в сценарий строки сообщений возможно перевести на язык интерфейса приложения. Строки в сценариях, которые являются частью официальной сборки KatePart, автоматически извлекаются и представляются для перевода командам переводчиков KDE. Другими словами, разработчикам основной ветви KatePart не приходится заниматься извлечением сообщений и их переводом. Впрочем, следует отметить, что перевод будет работать только в пределах инфраструктуры KDE, то есть перевод новых строк сценариев, разработанных за пределами KDE, невозможен. Поэтому созданные сценарии следует отправлять в основную ветвь разработки Kate, чтобы сделать возможным надлежащий перевод.

    void i18n(String текст, параметр1, ...);

  Перевести `текст` на язык интерфейса приложения. Параметры `параметр1`, ... являются необязательными. Они позволяют заменить строки `%1`, `%2` и так далее.

    void i18nc(String контекст, String текст, параметр1, ...);

  Перевести `текст` на язык интерфейса приложения. При этом переводчикам будет показана строка `контекст`, что облегчает перевод. Параметры `параметр1`, ... являются необязательными. Они позволяют заменить строки `%1`, `%2` и так далее.

    void i18np(String единственное, String множественное, int количество, параметр1, ...);

  Перевести `единственное` или `множественное` число сообщения на язык интерфейса приложения, в зависимости от указанного значения параметра `количество`. Параметры `параметр1`, ... являются необязательными. Они позволяют заменить строки `%1`, `%2` и так далее.

    void i18ncp(String контекст, String единственное, String множественное, int количество, параметр1, ...);

  Перевести `единственное` или `множественное` число сообщения на язык интерфейса приложения, в зависимости от указанного значения параметра `количество`. При этом переводчикам будет показана строка `контекст`, что облегчает перевод. Параметры `параметр1`, ... являются необязательными. Они позволяют заменить строки `%1`, `%2` и так далее.

#### Программный интерфейс (API) View

Каким бы образом ни был запущен сценарий, он всегда будет использовать глобальную переменную «`view`», которая соответствует текущей активной области просмотра. Далее приводится список всех доступных функций объекта «View».

    void view.copy()

  Копировать выбранный фрагмент, если таковой имеется. Когда ничего не выбрано, копировать текущую строку, если указан параметр `[ ] Вырезать или копировать текущую строку, если ничего не выделено`.

  Начиная с KDE Frameworks 5.79

    void view.cut()

  Вырезать выбранный фрагмент, если таковой имеется. Когда ничего не выбрано, вырезать текущую строку, если указан параметр `[ ] Вырезать или копировать текущую строку, если ничего не выделено`.

  Начиная с KDE Frameworks 5.79

    void view.paste()

  Вставить содержимое буфера обмена.

  Начиная с KDE Frameworks 5.79

    Cursor view.cursorPosition()

  Возвращает текущую позицию курсора в области просмотра.

    void view.setCursorPosition(int строка, int столбец);
    void view.setCursorPosition(Cursor курсор);

  Устанавливает для текущего курсора позицию (строка, столбец) или позицию указанного курсора.

    Cursor view.virtualCursorPosition();

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

    void view.setVirtualCursorPosition(int строка, int столбец);
    void view.setVirtualCursorPosition(Cursor курсор);

  Устанавливает для текущего виртуального курсора позицию (строка, столбец) или позицию указанного курсора.

    String view.selectedText();

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

    bool view.hasSelection();

  Возвращает `true`, если выделенный фрагмент текст находится в области просмотра, в ином случае — `false`.

    Range view.selection();

  Возвращает диапазон выделенного фрагмента текста. Если выделенного фрагмента текста нет, возвращается некорректный диапазон.

    void view.setSelection(Range диапазон);

  Устанавливает выделение текста по указанному диапазону.

    void view.removeSelectedText();

  Удаляет выделенный текст. Если в области просмотра отстутствует выделенный текст, никаких действий не выполняется.

    void view.selectAll();

  Выделяет весь текст в документе.

    void view.clearSelection();

  Снимает выделение с текста, не удаляя сам текст.

    void view.setBlockSelection(bool on);

  Включает или отключает режим выделения блока.

    bool view.blockSelection();

  Возвращает `true`, если режим выделения блока включён, в ином случае — `false`.

    void view.align(Range range);

  Надлежащим образом повторно расставляет отступы строк в пределах указанного диапазона `range` согласно текущим параметрам расстановки отступов.

    void view.alignOn(Range range, String pattern = "");

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

  Примеры:

  `view.alignOn(document.documentRange(), '-');` вставит пробелы перед первым `-` в каждой строке, чтобы выровнять все дефисы по одной позиции.

  `view.alignOn(document.documentRange(), ':\\s+(.)');` вставит пробелы перед первым непустым символом, стоящим после двоеточия, чтобы выровнять все такие символы по одной позиции.

    object view.executeCommand(String команда,
                               String параметры,
                               Range диапазон);

  Выполняет команду командной строки `command` с необязательными аргументами `args` и необязательным диапазоном `range`. Возвращённый объект `object` имеет логическое свойство `object.ok`, которое указывает на то, было ли успешным выполнение команды `command`. В случае ошибки строка `object.status` будет содержать сообщение об ошибке.

  Начиная с KDE Frameworks 5.50

    Range view.searchText(Range range,
                          String pattern,
                          bool backwards = false);

  Выполняет поиск первого вхождения `pattern` в `range` и возвращает найденный диапазон. Поиск выполняется в обратном направлении, если необязательный логический параметр `backwards` установлен в значение `true`.

  Возвращённый диапазон будет некорректным (смотрите Range.isValid()), если шаблон `pattern` не найден в диапазоне `range`.

  Начиная с KDE Frameworks 5.97

#### Программный интерфейс (API) Document

Каким бы образом ни был запущен сценарий, он всегда будет использовать глобальную переменную «`document`», которая соответствует текущему активному документу. Далее приводится список всех доступных функций объекта «Document».

    String document.fileName();

  Возвращает название файла документа или пустую строку для несохранённых буферов с текстом.

    String document.url();

  Возвращает полный URL-адрес документа или пустую строку для несохранённых буферов с текстом.

    String document.mimeType();

  Возвращает тип MIME документа или тип MIME `application/octet-stream`, если не удалось найти соответствующий тип MIME.

    String document.encoding();

  Возвращает текущую кодировку, которая будет использована для сохранения файла .

    String document.highlightingMode();

  Возвращает глобальный режим подсветки, используемый во всём документе.

    String document.highlightingModeAt(Cursor позиция);

  Возвращает режим подсветки, используемый в указанной позиции в документе.

    Array document.embeddedHighlightingModes();

  Возвращает массив режимов подсветки, встроенных в текущий документ.

    bool document.isModified();

  Возвращает `true`, если в документе имеются несохранённые изменения, в ином случае — `false`.

    String document.text();

  Возвращает всё содержимое документа в виде единой текстовой строки. Разрывы строк обозначаются символом перехода на новую строку «`\n`».

    String document.text(int соСтроки, int соСтолбца, int доСтроки, int доСтолбца);
    String document.text(Cursor с, Cursor до);
    String document.text(Range диапазон);

  Возвращает текст в указанном диапазоне. Чтобы код было легче читать, рекомендуется использовать основанную на объектах Cursor и Range версию функции.

    String document.line(int строка);

  Возвращает строку по её номеру в тексте. Если указанный номер находится вне диапазона номеров строк документа, возвращается пустая строка.

    String document.wordAt(int строка, int столбец);
    String document.wordAt(Cursor курсор);

  Возвращает слово в указанной позиции курсора.

    Range document.wordRangeAt(int строка, int столбец);
    Range document.wordRangeAt(Cursor курсор);

  Возвращает диапазон слова в указанной позиции курсора. Возвращённое значение диапазона будет некорректным (смотрите Range.isValid()), если текст находится за концом строки. Если в указанной позиции курсора отсутствует слово, возвращается пустой диапазон.

  Начиная с KDE 4.9

    String document.charAt(int строка, int столбец);
    String document.charAt(Cursor курсор);

  Возвращает символ в указанной позиции курсора.

    String document.firstChar(int строка);

  Возвращает первый отличный от пробела символ в указанной `строке`. Первым символом строки считается символ в столбце 0. Если строка является пустой или состоит только из пробелов, функция возвращает пустую строку.

    String document.lastChar(int строка);

  Возвращает последний отличный от пробела символ в указанной `строке`. Если строка является пустой или состоит только из пробелов, функция возвращает пустую строку.

    bool document.isSpace(int строка, int столбец);
    bool document.isSpace(Cursor курсор);

  Возвращает `true`, если символ в указанной позиции курсора является пробелом, в ином случае — `false`.

    bool document.matchesAt(int строка, int столбец, String текст);
    bool document.matchesAt(Cursor курсор, String текст);

  Возвращает `true`, если указанный `текст` расположен в соответствующей позиции курсора, в ином случае — `false`.

    bool document.startsWith(int строка, String текст, bool skipWhiteSpaces);

  Возвращает `true`, если строка с указанным номером начинается с фрагмента текста `текст`, в ином случае — `false`. Параметр `skipWhiteSpaces` позволяет указать программе, следует ли игнорировать пробелы в начале строки.

    bool document.endsWith(int строка, String текст, bool skipWhiteSpaces);

  Возвращает `true`, если строка с указанным номером заканчивается фрагментом текста `текст`, в ином случае — `false`. Параметр `skipWhiteSpaces` позволяет указать программе, следует ли игнорировать пробелы в конце строки.

    bool document.setText(String текст);

  Заменяет всё содержимое документа на указанный текст.

    bool document.clear();

  Удаляет весь текст в документе.

    bool document.truncate(int строка, int столбец);
    bool document.truncate(Cursor курсор);

  Обрезает строку с указанным номером на указанном столбце или в указанной позиции курсора. Возвращает `true` в случае успеха или `false`, если строка с указанным номером находится вне диапазона номеров строк документа.

    bool document.insertText(int строка, int столбец, String текст);
    bool document.insertText(Cursor курсор, String текст);

  Вставляет указанный `текст` в указанной позиции курсора. Возвращает `true` в случае успеха или `false`, если документ доступен только для чтения.

    bool document.removeText(int соСтроки, int соСтолбца, int доСтроки, int доСтолбца);
    bool document.removeText(Cursor с, Cursor до);
    bool document.removeText(Range диапазон);

  Удаляет текст в указанном диапазоне. Возвращает `true` в случае успеха или `false`, если документ доступен только для чтения.

    bool document.insertLine(int строка, String текст);

  Вставляет текст в указанной строке. Возвращает `true` в случае успеха или `false`, если документ доступен только для чтения или указанная строка находится вне диапазона номеров строк документа.

    bool document.removeLine(int строка);

  Удаляет строку с указанным номером. Возвращает `true` в случае успеха или `false`, если документ доступен только для чтения или указанная строка находится вне диапазона номеров строк документа.

    bool document.wrapLine(int строка, int столбец);
    bool document.wrapLine(Cursor курсор);

  Переносит строку по указанной позиции курсора. Возвращает `true` в случае успеха или `false` (например, если номер строки < 0).

  Начиная с KDE 4.9

    void document.joinLines(int начальнаяСтрока, int конечнаяСтрока);

  Соединяет строки в диапазоне от `начальнаяСтрока` до `конечнаяСтрока`. Две последовательные текстовые строки всегда разделяются одиночным пробелом.

    int document.lines();

  Возвращает число строк в документе.

    bool document.isLineModified(int строка);

  Возвращает `true`, если `строка` в настоящее время содержит несохранённые данные.

  Начиная с KDE 5.0

    bool document.isLineSaved(int строка);

  Возвращает `true`, если `строка` была изменена и затем документ был сохранён. Следовательно, в настоящее время строка не содержит какие-либо несохранённые данные.

  Начиная с KDE 5.0

    bool document.isLineTouched(int строка);

  Возвращает `true`, если `строка` в настоящее время содержит несохранённые данные или была изменена ранее.

  Начиная с KDE 5.0

    bool document.findTouchedLine(int начальнаяСтрока, bool down);

  Поиск следующей изменённой строки, начиная со строки `начальнаяСтрока`. Поиск выполняется в направлении «вверх» (к началу документа) или «вниз» (к концу документа), в зависимости от значения параметра `down`.

  Начиная с KDE 5.0

    int document.length();

  Возвращает число символов в документе.

    int document.lineLength(int строка);

  Возвращает длину строки с номером `строка`.

    void document.editBegin();

  Начинает группу редактирования для упорядочения операций отмены или повтора действий. Не забывайте, что вызывать `editEnd()` следует именно столько раз, сколько вызывается `editBegin()`. Вызовы `editBegin()` используют встроенный счётчик, следовательно, их возможно вкладывать один в другой.

    void document.editEnd();

  Завершает группу редактирования. Последний вызов `editEnd()` (то есть соответствие первого вызова `editBegin()`) завершает шаг по редактированию.

    int document.firstColumn(int строка);

  Возвращает первый отличный от пробела столбец в указанной с помощью параметра `строка` строке. Если в строке будут только пробелы, функция вернёт значение `-1`.

    int document.lastColumn(int строка);

  Возвращает последний отличный от пробела столбец в указанной с помощью параметра `строка` строке. Если в строке будут только пробелы, функция вернёт значение `-1`.

    int document.prevNonSpaceColumn(int строка, int столбец);
    int document.prevNonSpaceColumn(Cursor курсор);

  Возвращает номер столбца с символом, отличным от пробела. Поиск будет выполнен в направлении начала документа, начиная с указанной позиции курсора.

    int document.nextNonSpaceColumn(int строка, int столбец);
    int document.nextNonSpaceColumn(Cursor курсор);

  Возвращает номер столбца с символом, отличным от пробела. Поиск будет выполнен в направлении конца документа, начиная с указанной позиции курсора.

    int document.prevNonEmptyLine(int строка);

  Возвращает следующую непустую строку, содержащую отличные от пробелов символы. Поиск будет выполнен в направлении начала документа.

    int document.nextNonEmptyLine(int строка);

  Возвращает следующую непустую строку, содержащую отличные от пробелов символы. Поиск будет выполнен в направлении конца документа.

    bool document.isInWord(String символ, int атрибут);

  Возвращает `true`, если указанный `символ` с указанным параметром `атрибут` может быть частью слова, в ином случае — `false`.

    bool document.canBreakAt(String символ, int атрибут);

  Возвращает `true`, если указанный `символ` с указанным параметром `атрибут` может быть использован как место переноса строки, в ином случае — `false`.

    bool document.canComment(int начальныйАтрибут, int конечныйАтрибут);

  Возвращает `true`, если диапазон, начало и конец которого определяются на основе указанных атрибутов, может быть закомментирован, в ином случае — `false`.

    String document.commentMarker(int атрибут);

  Возвращает метку комментария для однострочных комментариев для указанного параметра `атрибут`.

    String document.commentStart(int атрибут);

  Возвращает метку комментария для начала многострочных комментариев для указанного параметра `атрибут`.

    String document.commentEnd(int атрибут);

  Возвращает метку комментария для завершения многострочных комментариев для указанного параметра `атрибут`.

    Range document.documentRange();

  Возвращает диапазон, который включает весь документ.

    Cursor documentEnd();

  Возвращает курсор, расположенный в последнем столбце последней строки в документе.

    bool isValidTextPosition(int строка, int столбец);
    bool isValidTextPosition(Cursor курсор);

  Возвращает `true`, если курсор находится в корректной позиции в тексте. Позиция в тексте является корректной, только если курсор находится в начале, в середине или в конце корректной строки текста. Кроме того, позиция в тексте является некорректной, если курсор находится в заменителе символа Юникода.

  Начиная с KDE 5.0

    int document.attribute(int строка, int столбец);
    int document.attribute(Cursor курсор);

  Возвращает атрибут в указанной позиции курсора.

    bool document.isAttribute(int строка, int столбец, int атрибут);
    bool document.isAttribute(Cursor курсор, int атрибут);

  Возвращает `true`, если атрибут в указанной позиции курсора совпадает со значением параметра `атрибут`, в ином случае — `false`.

    String document.attributeName(int строка, int столбец);
    String document.attributeName(Cursor курсор);

  Возвращает название атрибута как удобочитаемый текст. Соответствует названию `itemData` в файлах подсветки синтаксиса.

    bool document.isAttributeName(int строка, int столбец, String название);
    bool document.isAttributeName(Cursor курсор, String название);

  Возвращает `true`, если название атрибута в определённой позиции курсора соответствует указанному значению параметра `название`, в ином случае — `false`.

    String document.variable(String ключ);

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

    void document.setVariable(String ключ, String значение);

  Устанавливает значение соответствующей переменной документа `ключ`.

  Смотрите также переменные документа Kate

  Начиная с KDE 4.8

    int document.firstVirtualColumn(int строка);

  Возвращает виртуальный столбец первого отличного от пробела символа в указанной строке или `-1`, если строка является пустой или содержит только пробелы.

    int document.lastVirtualColumn(int строка);

  Возвращает виртуальный столбец последнего отличного от пробела символа в указанной строке или `-1`, если строка является пустой или содержит только пробелы.

    int document.toVirtualColumn(int строка, int столбец);
    int document.toVirtualColumn(Cursor курсор);
    Cursor document.toVirtualCursor(Cursor курсор);

  Преобразует указанную «реальную» позицию курсора в виртуальную позицию курсора, возвращая либо целое значение (int), либо объект «Cursor».

    int document.fromVirtualColumn(int строка, int виртуальныйСтолбец);
    int document.fromVirtualColumn(Cursor виртуальныйКурсор);
    Cursor document.fromVirtualCursor(Cursor виртуальныйКурсор);

  Преобразует указанную виртуальную позицию курсора в «реальную» позицию курсора, возвращая либо целое значение (int), либо объект «Cursor».

    Cursor document.anchor(int строка, int столбец, Char символ);
    Cursor document.anchor(Cursor курсор, Char символ);

  Выполняет поиск указанного символа в направлении начала документа, начиная в указанной позиции курсора. Например, если функции будет передан символ «(», она вернёт позицию открывающей скобки «(». Выполняется подсчёт ссылок, то есть другие «(...)» будут проигнорированы.

    Cursor document.rfind(int строка, int столбец, String текст, int атрибут = -1);
    Cursor document.rfind(Cursor курсор, String текст, int атрибут = -1);

  Выполняет поиск указанного текста с соответствующим значением параметра `атрибут` в направлении начала текста. Параметр `атрибут` игнорируется, если он установлен в значение `-1`. Возвращает некорректный курсор, если текст не удалось найти.

    int document.defStyleNum(int строка, int столбец);
    int document.defStyleNum(Cursor курсор);

  Возвращает стиль по умолчанию, используемый в указанной позиции курсора.

    bool document.isCode(int строка, int столбец);
    bool document.isCode(Cursor курсор);

  Возвращает `true`, если атрибут в указанной позиции курсора не совпадает ни с одним из следующих значений стилей: `dsComment`, `dsString`, `dsRegionMarker`, `dsChar`, `dsOthers`.

    bool document.isComment(int строка, int столбец);
    bool document.isComment(Cursor курсор);

  Возвращает `true`, если значением атрибута символа в позиции курсора является `dsComment`, в ином случае — `false`.

    bool document.isString(int строка, int столбец);
    bool document.isString(Cursor курсор);

  Возвращает `true`, если значением атрибута символа в позиции курсора является `dsString`, в ином случае — `false`.

    bool document.isRegionMarker(int строка, int столбец);
    bool document.isRegionMarker(Cursor курсор);

  Возвращает `true`, если значением атрибута символа в позиции курсора является `dsRegionMarker`, в ином случае — `false`.

    bool document.isChar(int строка, int столбец);
    bool document.isChar(Cursor курсор);

  Возвращает `true`, если значением атрибута символа в позиции курсора является `dsChar`, в ином случае — `false`.

    bool document.isOthers(int строка, int столбец);
    bool document.isOthers(Cursor курсор);

  Возвращает `true`, если значением атрибута символа в позиции курсора является `dsOthers`, в ином случае — `false`.

    void document.indent(Range range, int change);

  Устанавливает отступы для всех строк в диапазоне `range` на `change` табуляций или `change` раз на `tabSize` пробелов (в зависимости от выбранных пользователем параметров). Значение параметра `change` может быть отрицательным.

#### Программный интерфейс (API) редактора

Кроме программного интерфейса документа и области просмотра, существует и общий программный интерфейс редактора, который предоставляет доступ к общим функциям управления редактором с помощью сценариев.

    String editor.clipboardText();

  Возвращает текст, который в настоящее время находится в глобальном буфере обмена.

  Начиная с KDE Frameworks 5.50

    String editor.clipboardHistory();

  Редактор сохраняет журнал буфера обмена, который содержит до 10 записей. Эта функция возвращает все записи, которые в настоящее время находятся в журнале буфера обмена.

  Начиная с KDE Frameworks 5.50

    void editor.setClipboardText(String текст);

  Устанавливает для содержимого буфера обмена значение `текст`. Запись `текст` будет добавлена в журнал буфера обмена.

  Начиная с KDE Frameworks 5.50

Глава 7. Настройка KatePart
Настройка KatePart

# Глава 7. Настройка KatePart

Выберите пункт меню Настройка → Настроить `редактор`...: будет открыто окно Настройка. Здесь возможно изменять различные параметры программы. Параметры сгруппированы по разделам, которые перечислены в списке слева. Независимо от выбранного раздела в нижней части окна присутствуют три стандартные кнопки управления процессом настройки.

Кнопка Справка позволяет вызвать справочную систему, кнопка OK — сохранить текущие параметры и закрыть диалог, кнопка Отмена — закрыть диалог без сохранения изменений. Далее приводится описание разделов настройки (Внешний вид, Шрифты и цвета, Редактирование, Открытие и сохранение и Расширения).

## Настройка компонента редактирования

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

### Внешний вид

#### Главное

Шрифт редактора

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

  Дополнительные сведения о выборе шрифта доступны в разделе Выбор шрифта в Основах KDE.

Показывать маркеры пробелов
  Никогда

    В редакторе не будут показаны точки, обозначающие наличие пробелов.

  В конце строки

    В редакторе будут показаны точки, обозначающие наличие дополнительных пробелов в конце строки.

  Всегда

    В редакторе будут показаны точки, обозначающие наличие пробелов.

Размер маркеров пробелов

  Ползунок позволяет изменять размер видимого маркера.

Показывать маркеры табуляции

  Если флажок установлен, в редакторе будет показан символ », обозначающий наличие табуляции в тексте.

Поиск и подсветка пар скобок

  Выделять пространство между скобками

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

  Предварительный просмотр парной открытой скобки

    Если флажок установлен, в редакторе будет показана подсказка с парной открытой скобкой.

  Мигание парной скобки при наведении курсора на другую скобку в паре

    Если флажок установлен, при переходе между скобками ({, [, ], },( или )) соответствующая парная скобка будет мигать.

Показать линии отступов

  Если флажок установлен, в редакторе будут видны вертикальные линии, облегчающие поиск строк с одинаковыми отступами.

Счётчики

  Показать счётчик слов и символов

    В строке состояния отображается количество слов и символов в документе и в текущем выделенном фрагменте. Этот параметр также доступен в контекстном меню строки состояния.

  Показать счётчик строк

    В строке состояния отображается общее количество строк в документе. Этот параметр также доступен в контекстном меню строки состояния.

Сворачивать блок, начинающийся в первой строке

  Если этот параметр включён, блок, который начинается в первой строке, будет свёрнут. Это полезно в тех случаях, когда файл начинается с комментария (например, с информации об авторских правах).

Динамический перенос строк

  Если флажок установлен, слова, не помещающиеся в видимую часть экрана, будут автоматически перенесены на новую строку.

  Динамический перенос строк по маркеру статического переноса

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

  Игнорировать границы слов для динамического переноса

    Если флажок установлен, редактор не учитывает границы слов при динамическом переносе строк текста.

Маркеры динамического переноса строк

  Позволяет выбрать вариант показа маркеров динамического переноса строк: Выключить, За номерами строк или Видны всегда.

Добавлять отступы для перенесённых строк

  Кроме того, этот параметр позволяет установить максимальную ширину экрана (в процентах), после превышения которой динамически перенесенные строки не будут выравниваться по отступу. Например, при значении 50% строки с отступом больше 50% ширины экрана больше не будут выравниваться по отступу.

Коэффициент высоты строки

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

#### Границы

Сворачивание блоков кода
  Показывать маркеры сворачивания блоков кода

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

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

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

Видимость стрелок свёртывания

  Переключение стрелок свёртывания: Показывать при наведении или Показывать всегда.

Левая сторона
  Показывать отметки

    Включает показ полосы закладок в левой части редактора.

  Показывать номера строк

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

  Выделять изменённые и несохранённые строки

    Если флажок установлен, будут показаны маркеры изменённых строк. Дополнительные сведения: «Маркеры изменённых строк».

Полосы прокрутки
  Показывать отметки

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

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

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

Мини-карта
  Показывать мини-карту

    Если флажок установлен, каждое новое представление будет содержать мини-карту документа на вертикальной полосе прокрутки.

    Дополнительные сведения о мини-карте в полосе прокрутки: «Мини-карта в полосе прокрутки».

  Ширина мини-карты

    Регулирует ширину мини-карты в полосе прокрутки (в пикселах).

  Видимость полос прокрутки

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

Сортировка закладок в меню
  По дате создания

    Каждая новая закладка будет добавлена в конец списка, вне зависимости от того, на какой строке документа она установлена.

  По номеру строки

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

### Цветовые схемы

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

При входе в диалог KatePart автоматически выбирает текущую активную схему. Если требуется внести изменения в другую схему, возможно выбрать её в раскрывающемся списке Схема. Кнопки Копировать… и Удалить предназначены, соответственно, для создания новых схем (путём копирования существующих) и удаления существующих схем.

Подробнее: «Графический интерфейс цветовых схем».

### Редактирование

#### Главное

Перенос строк

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

  Переносить слова на фиксированной позиции

    Включает или отключает статический перенос строк.

  Показывать вертикальную линию в позиции переноса строк

    Если этот параметр включён, на столбце с переносимыми строками будет показана вертикальная линия (настраивается с помощью пункта меню Настройка → Настроить редактор... на вкладке «Редактирование»). Обратите внимание, маркер будет виден только в том случае, если используется моноширинный шрифт.

  Переносить слова на новую строку после:

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

Режим ввода по умолчанию

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

Скобки

  Если параметр Автоматически закрывать скобки при вводе открывающей скобки включён, когда пользователь введёт символ открывающей скобки ([, ( или {), KatePart автоматически вставит закрывающую скобку (}, ) или ]) справа от курсора.

Символы-ограничители

  Возможно выбрать символы-ограничители с помощью соответствующего раскрывающегося списка.

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

Копирование и вставка
  Перемещать выделенный текст при перетаскивании

    Этот параметр включает перетаскивание выделенного текста внутри окна редактора.

  Вырезать или копировать текущую строку, если ничего не выделено

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

  Не перемещать текстовый курсор при вставке с помощью мыши

    Если этот параметр включён, при вставке какого-либо текста в окно редактора щелчком средней кнопкой мыши KatePart не будет перемещать текстовый курсор в позицию щелчка.

#### Навигация по тексту

Перемещение курсора
  Интеллектуальная навигация клавишами «Home» и «End»

    Если флажок установлен, при нажатии клавиши Home курсор будет переходить на начало текста в текущей строке, игнорируя пробелы в начале строки.

  Клавиши PageUp и PageDown перемещают курсор

    Этот параметр определяет реакцию курсора на нажатие клавиш PgUp и PgDn. Если флажок снят, курсор будет сохранять свою относительную позицию в окне. Следовательно, если до нажатия клавиши курсор был в середине окна, он там и останется после нажатия (если, конечно, не достигнут конец или начало документа). Если флажок установлен, первое нажатие клавиши переместит курсор вниз или вверх экрана.

  Включить переход курсора к прописным буквам

    Этот параметр изменяет поведение курсора при нажатии комбинации клавиш Ctrl+стрелка влево или Ctrl+стрелка вправо пользователем. Если флажок снят, текстовый курсор переходит к следующему полному слову. Если флажок установлен, курсор будет останавливаться на прописных буквах в словах, написанных буквамиразных регистров.

  Оставлять между курсором и краем строк

    Устанавливает число строк, которые должны быть видимы выше и ниже курсора (если возможно).

Режим выделения текста
  Обычный

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

  Не снимать выделение

    Выделение не изменяется даже после ввода текста и перемещения курсора.

  Позволять прокручивать документ ниже его конца

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

  Клавиша Backspace удаляет символ совместно с его диакритическим знаком

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

Модификатор множественных курсоров

  Этот параметр позволяет задать модификатор, который будет использоваться для создания множественных курсоров по щелчку левой кнопкой мыши. Чтобы создать курсор в выбранном месте, следует нажать модификатор и щёлкнуть левой кнопкой мыши. Для ознакомления с другими способами создания множественных курсоров обратитесь к разделу Создание множественных курсоров.

#### Отступы

Режим расстановки отступов по умолчанию

  Позволяет выбрать используемый по умолчанию автоматический режим расстановки отступов. Настоятельно рекомендуется выбрать `Без автоматического отступа` или `Обычный`, а другие пункты выбирать при настройке разных типов файлов, таких как код на C/C++ или файлы в формате XML.

Отступы
  Табуляция

    Если флажок установлен, при нажатии клавиши Tab или использовании функции автоматического отступа редактор будет вставлять символы табуляции.

  Пробелы

    Если флажок установлен, при нажатии клавиши Tab или использовании функции автоматического отступа редактор будет вставлять необходимое количество пробелов в соответствии с положением в тексте и значением параметра `ширины табуляции`.

  Табуляция и пробелы

    Если флажок установлен, редактор при создании отступа или нажатии клавиши Tab в начале строки будет вставлять пробелы как описано выше, а при нажатии клавиши Tab в середине или конце строки — символы табуляции.

  Ширина табуляции

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

  Ширина отступа

    Ширина отступа — это количество пробелов для обозначения отступа строки. Если задано создание отступов с помощью символов табуляции, будет вставлен символ табуляции (при условии, что отступ кратен ширине табуляции).

Правила расстановки отступов
  Сохранять лишние пробелы

    Если флажок снят, при изменении уровня отступа строка будет выровнена согласно значению параметра Ширина отступа.

  Выполнять расстановку отступов для вставляемого из буфера обмена кода

    Если флажок установлен, во вставленном из буфера обмена тексте будут созданы отступы. Команда Отменить действие позволяет убрать созданные отступы.

Работа с отступами
  Уменьшение отступа клавишей Backspace

    Если флажок установлен, нажатие клавиши Backspace будет уменьшать уровень отступа, когда курсор располагается в пустом пространстве в начале строки.

  Действие при нажатии клавиши Tab (если ничего не выделено)

    Если при нажатии клавиши Tab текущая строка должна выравниваться в текущем блоке кода как в Emacs, следует установить привязку клавиши Tab к действию Форматированный отступ.

    Всегда добавлять табуляцию (либо эквивалентное количество пробелов)

      Если флажок установлен, при нажатии клавиши Tab будут автоматически вставлены символы пустого пространства до достижения следующей позиции табуляции. Если параметр Отступы пробелами вместо символов табуляции (вкладка Главное на странице Редактирование) включён, будут вставлены пробелы; в ином случае будет вставлен один символ табуляции.

    Всегда увеличивать уровень отступа

      Если флажок установлен, при нажатии клавиши Tab для текущей строки всегда будет создаваться отступ на количество символов, заданное параметром Ширина отступа.

    Увеличивать уровень отступа, если курсор стоит в начале строки

      Если флажок установлен, при нажатии клавиши Tab будет либо создан отступ для текущей строки, либо выполнен переход к следующей позиции табуляции. Если точкой вставки является первый непробельный символ строки или какой-либо из предшествующих ему или если имеется выбранный фрагмент, то для текущей строки будет создан отступ на количество символов, заданное параметром Ширина отступа. Если точка вставки располагается после первого непробельного символа строки и ничего не выбрано, вставляется пустое пространство до достижения следующей позиции табуляции: если параметр Отступы пробелами вместо символов табуляции (вкладка Главное на странице Редактирование) включён, будут вставлены пробелы; в ином случае будет вставлен один символ табуляции.

#### Автодополнение

Главное
  Включить автодополнение

    Если флажок установлен, при наборе текста автоматически всплывает окно автодополнения, в котором показан список вариантов завершения текущего слова под курсором.

  Автоматически выбирать первую запись дополнения

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

Минимальная длина слова для автодополнения

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

Удалять окончание при завершении

  Удалять окончание предыдущего слова при выборе варианта завершения в списке.

Автодополнение ключевых слов

  Если флажок установлен, встроенное автодополнение будет использовать ключевые слова, определённые подсветкой синтаксиса.

#### Проверка правописания

Описание этих параметров настройки приводится в документации модуля Проверка орфографии программы «Параметры системы».

#### Режим ввода Vi

Главное
  Использовать комбинации клавиш Vi

    Если флажок установлен, команды Vi будут иметь приоритет над встроенными командами KatePart. Например: при использовании комбинации клавиш Ctrl+R будет выполнена команда «Повторить», а не стандартное действие (вызов диалога поиска и замены).

  Показать относительные номера строк

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

Замена действий клавиш

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

  Пример:

  F2 -> `I--` Esc

  Добавить `I--` в начало строки, когда будет нажата клавиша F2.

### Открытие и сохранение

#### Главное

Формат файла
  Кодировка

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

  Автоопределение кодировки

    Выберите один из вариантов в раскрывающемся списке: возможно отключить автоопределение или указать вариант Универсальная, чтобы включить автоопределение для всех кодировок. Но так как в этом случае получится определить, скорее всего, только utf-8/utf-16, для получения наилучшего результата рекомендуется выбрать региональный вариант со специальными эвристическими методами. Выбранный вариант будет использоваться в том случае, если содержимому файла не соответствует ни кодировка, выбранная в качестве стандартной выше, ни кодировка, заданная в диалоге открытия или сохранения, ни кодировка, указанная в командной строке.

  Резервная кодировка

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

  Конец строки

    Позволяет выбрать необходимый режим конца строк для документа. Доступные варианты: UNIX®, DOS/Windows®, Macintosh.

  Автоматическое определение символов конца строки

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

  Использовать отметку о порядке байтов (BOM)

    Отметка о порядке байтов — это специальная последовательность в начале документов в кодировке Юникод. Наличие этой отметки позволяет редакторам открывать текстовые документы в соответствующей кодировке Юникод. Дополнительные сведения: Маркер последовательности байтов.

  Ограничение на длину строки

    К сожалению, из-за недоработок в Qt™ производительность KatePart резко снижается при работе с очень длинными строками. Поэтому в KatePart выполняется автоматический перенос строк, длина которых превышает указанную здесь. Чтобы убрать ограничение, установите этот параметр в значение `0`.

Автоматическая очистка при сохранении
  Удалять пробелы в конце строк

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

  Добавлять перевод строки в конец файла при сохранении

    Редактор автоматически добавит перевод строки в конец файла (если такой перевод отсутствует) при сохранении этого файла.

Включить автосохранение (только для локальных файлов)

  Установите флажок, чтобы редактор автоматически сохранял документы во время работы над ними.

  Автоматически сохранять документ при утрате фокуса редактором

    Редактор будет автоматически сохранять документы при переключении на что-то вне его самого (например, на панель терминала в Kate).

  Интервал автосохранения

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

#### Дополнительно

Создавать резервную копию при сохранении

  Если флажок установлен, KatePart копирует используемый файл (ранее сохранённую версию файла) в <префикс><имя_файла><суффикс> перед сохранением новых изменений. Файл резервной копии поможет восстановить наработки, если что-то пошло не так во время сохранения или если в дальнейшем потребуется предыдущая версия файла. По умолчанию используется суффикс ~, а префикс не используется.

  Для локальных файлов

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

  Для удалённых файлов

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

  Префикс для файлов резервных копий

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

  Суффикс для файлов резервных копий

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

  Режим временных файлов

    Если приложение аварийно завершит работу или произойдёт отключение электроэнергии, будет возможно восстановить (в большинстве своём) текст, который не был сохранён. При редактировании документа создаётся временный файл (.<имя_файла>.kate-swp). Если внесённые изменения не были сохранены пользователем и произошёл сбой KatePart, этот временный файл остаётся на диске. При открытии файла KatePart проверяет, имеется ли для этого документа временный файл. Если таковой обнаружен, пользователю будет предложено выбрать, следует ли восстановить потерянные данные. Приложение также позволяет просмотреть различия между оригинальным файлом и его восстановленной версией. Временный файл удаляется после каждого сохранения и при обычном завершении работы приложения.

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

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

  Сохранять временные файлы в

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

  Сохранять временные файлы каждые

    KatePart выполняет синхронизацию находящихся на диске временных файлов каждые 15 секунд, но только в том случае, если имеются изменения с момента последней синхронизации. Интервал синхронизации возможно настроить в соответствии с потребностями пользователя.

#### Типы файлов

Этот раздел позволяет переопределить параметры для документов определённого типа MIME. При загрузке документа редактор проверяет, совпадает ли файл с одной из масок файлов или же с одним из типов MIME. В случае совпадения редактор применяет заданные параметры. Если совпадений несколько, будут применены параметры типа с наивысшим приоритетом.

Тип файла

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

  Создать

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

  Удалить

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

Свойства `выбранного_типа_файла`

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

  Имя

    Имена типов файлов будут использованы как текст соответствующих пунктов меню. Они отображаются в меню Сервис → Тип документа.

  Раздел

    Название раздела используется для организации типов файлов в пунктах меню. Оно также отображается в меню Сервис → Тип документа.

  Переменные

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

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

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

  Подсветка

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

  Режим расстановки отступов

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

  Расширения файлов

    Поле Расширения файлов содержит список масок, разделённых точками с запятой. Маска позволяет определить тип файла по его имени. Обычно в маске используются звёздочка и расширение файла, например `*.txt;*.text`.

  Типы MIME

    В поле Типы MIME возможно указать типы MIME, которые соответствуют текущему типу файла. Кнопка с изображением волшебной палочки справа от поля позволяет вызвать мастер, с помощью которого возможно легко выбрать типы MIME.

  Приоритет

    Последнее поле устанавливает приоритет для данного типа файла. Если для текущего документа доступно больше одного типа файлов, будет использован тип с наивысшим приоритетом.

Настройка с помощью переменных документа
Настройка с помощью переменных документа

## Настройка с помощью переменных документа

Переменные KatePart представляют собой реализацию переменных документа в KatePart, схожую с моделайнами Emacs и Vi. В KatePart строки имеют следующий формат: `kate: ИМЯПЕРЕМЕННОЙ ЗНАЧЕНИЕ; [ ИМЯПЕРЕМЕННОЙ ЗНАЧЕНИЕ; ... ]` Конечно, строки могут находиться в комментарии, если формат файла предусматривает комментарии. Имена переменных — это отдельные слова (без пробелов), а текст до следующей точки с запятой является значением. Указание точки с запятой обязательно.

Пример строки переменной для принудительного применения параметров отступа в файле C++, Java™ или JavaScript:

    // kate: replace-tabs on; indent-width 4; indent-mode cstyle;

### Примечание

Проверка наличия строк переменных выполняется только для первых и последних 10 строк.

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

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

KatePart поддерживает чтение конфигурации из файлов `.editorconfig` (если установлена библиотека editorconfig). При открытии документа KatePart выполняет автоматический поиск файла `.editorconfig`. Но приоритет всё же имеют файлы `.kateconfig`.

### Как в KatePart используются переменные

При чтении конфигурации KatePart выполняет поиск в следующих расположениях (в указанном далее порядке):

- Глобальная конфигурация.

- Необязательные данные сеанса.

- Конфигурация «типа файла».

- Переменные документа в файле `.kateconfig`.

- Переменные документа в самом документе.

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

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

Те переменные, которые не указаны в приведённом далее списке, хранятся в документе и могут запрашиваться для использования другими объектами (такими, как модули). Например, переменные документа используются для конфигурации соответствующего режима расстановки отступов.

Переменные, которые указаны в приведённом далее списке, соответствуют KatePart версии 5.38. В дальнейшем могут быть добавлены и другие переменные. Для переменных существуют 3 возможных типа значений со следующими допустимыми выражениями:

- BOOL — on|off|true|false|1|0

- INTEGER — любое целое число

- STRING — что-либо ещё

### Доступные переменные

auto-brackets [BOOL]

  Включить автоматическую вставку скобок.

auto-center-lines [INT]

  Указать количество строк для автоматического центрирования.

background-color [STRING]

  Указать цвет фона документа. Значение должно соответствовать допустимому цвету, например: `#ff0000`.

backspace-indents [BOOL]

  Включить или отключить отмену отступа при нажатии клавиши Backspace.

block-selection [BOOL]

  Включить или отключить выделение блоков.

bom | byte-order-mark | byte-order-marker [BOOL]

  Включить или отключить отметку о порядке байтов (BOM) при сохранении файлов в формате Юникод (utf8, utf16, utf32).

  Работает с версией Kate не ниже 3.4 (KDE 4.4)

bracket-highlight-color [STRING]

  Указать цвет подсветки скобок. Значение должно соответствовать допустимому цвету, например: `#ff0000`.

current-line-color [STRING]

  Указать цвет текущей строки. Значение должно соответствовать допустимому цвету, например: `#ff0000`.

default-dictionary [STRING]

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

  Работает с версией Kate не ниже 3.4 (KDE 4.4)

dynamic-word-wrap [BOOL]

  Включить или отключить динамический перенос строк.

eol | end-of-line [STRING]

  Указать режим конца строк. Допустимые параметры: `unix`, `mac` и `dos`.

folding-markers [BOOL]

  Включить или отключить показ полосы сворачивания блоков кода.

folding-preview [BOOL]

  Включить предварительный просмотр свёрнутых блоков кода.

font-size [INT]

  Указать размер шрифта документа.

font [STRING]

  Указать шрифт документа. Значением должно быть корректное название шрифта, например: `courier`.

hl | syntax [STRING]

  Указать подсветку синтаксиса. Допустимые строки — все названия, доступные в меню. Например, для подсветки C++ следует просто ввести `C++`.

icon-bar-color [STRING]

  Указать цвет полосы отметок. Значение должно соответствовать допустимому цвету, например: `#ff0000`.

icon-border [BOOL]

  Включить или отключить показ полосы отметок.

indent-mode [STRING]

  Указать режим автоматической расстановки отступов. Возможные параметры: `none`, `normal`, `cstyle`, `haskell`, `lilypond`, `lisp`, `python`, `ruby` и `xml`. Подробные сведения: «Использование автоматической расстановки отступов».

indent-pasted-text [BOOL]

  Включить или отключить расстановку отступов во вставленном из буфера обмена тексте.

  Работает с версией Kate не ниже 3.11 (KDE 4.11)

indent-width [INT]

  Указать ширину отступа.

keep-extra-spaces [BOOL]

  Указать, следует ли сохранять лишние пробелы при расчёте ширины отступа.

line-numbers [BOOL]

  Включить или отключить показ номеров строк.

newline-at-eof [BOOL]

  Добавлять пустую строку в конце файла (EOF) при сохранении документа.

  Работает с версией Kate не ниже 3.9 (KDE 4.9)

overwrite-mode [BOOL]

  Включить или отключить режим перезаписи.

persistent-selection [BOOL]

  Включить или отключить постоянное выделение.

replace-tabs-save [BOOL]

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

replace-tabs [BOOL]

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

remove-trailing-spaces [STRING]

  Удалять пробелы в конце строк при сохранении документа. Допустимые параметры:

  - `none`, `-` или `0`: никогда не удалять пробелы в конце строк.

  - `modified`, `mod`, `+` или `1`: удалять пробелы в конце только тех строк, которые были изменены. Изменённые строки отмечаются системой изменения строк.

  - `all`, `*` или `2`: удалять пробелы в конце строк во всём документе.

scrollbar-minimap [BOOL]

  Показывать мини-карту в полосе прокрутки.

scrollbar-preview [BOOL]

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

scheme [STRING]

  Указать цветовую схему. Чтобы команда сработала, строка должна содержать название существующей в конфигурации цветовой схемы.

selection-color [STRING]

  Указать цвет выделения. Значение должно соответствовать допустимому цвету, например: `#ff0000`.

show-tabs [BOOL]

  Включить или отключить показ знака табуляции.

smart-home [BOOL]

  Включить или отключить интеллектуальную навигацию клавишей «Home».

tab-indents [BOOL]

  Включить или отключить создание отступа по нажатию клавиши Tab.

tab-width [INT]

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

undo-steps [INT]

  Указать количество действий, которые возможно отменить.

  Примечание: не используется, начиная с Kate 3 в KDE4. Эта переменная игнорируется. Максимальное количество действий, которые возможно отменить, не ограничено.

word-wrap-column [INT]

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

word-wrap-marker-color [STRING]

  Указать цвет маркера переноса строк. Значение должно соответствовать допустимому цвету, например: `#ff0000`.

word-wrap [BOOL]

  Включить или отключить статический перенос строк.

### Расширенные параметры в файлах `.kateconfig`

KatePart всегда выполняет поиск файла `.kateconfig` при открытии локальных файлов (не сетевых). Кроме того, возможно указать параметры на основе масок (расширений файлов) следующим образом:

    kate: tab-width 4; indent-width 4; replace-tabs on;
    kate-wildcard(*.xml): indent-width 2;
    kate-wildcard(Makefile): replace-tabs off;

В этом примере для всех файлов используется ширина табуляции, равная 4 пробелам, и знаки табуляции заменяются пробелами. Но для всех файлов с расширением `*.xml` задана ширина табуляции, равная 2 пробелам. А для файлов Makefile используются знаки табуляции, то есть они не заменяются пробелами.

Маски разделяются точкой с запятой. Возможно указать несколько расширений файлов:

    kate-wildcard(*.json;*.xml): indent-width 2;

Более того, возможно использовать тип MIME. Например, чтобы проставить во всех исходных файлах C++ отступы шириной 4 пробела:

    kate-mimetype(text/x-c++src): indent-width 4;

### Примечание

Переменные документа возможно использовать не только задействуя файлы `.kateconfig`, маски и типы MIME, но и сам документ (в нём они представлены в виде комментариев).

Глава 8. Авторские права и лицензия
Авторские права и лицензия

# Глава 8. Авторские права и лицензия

Авторские права на KatePart и KWrite: (c) Команда разработчиков Kate, 2001—2022.

Программа основана на первоначальной версии KWrite, авторские права на которую принадлежат Jochen Wilhelmy `(digisnap AT cs.tu-berlin.de)`, 2000.

Участники проекта:

- Christoph Cullmann `(cullmann AT kde.org)`

- Michael Bartl `(michael.bartl1 AT chello.at)`

- Phlip `(phlip_cpp AT my-deja.com)`

- Anders Lund `(anders AT alweb.dk)`

- Matt Newell `(newellm AT proaxis.com)`

- Joseph Wenninger `(kde AT jowenn.at)`

- Jochen Wilhelmy `(digisnap AT cs.tu-berlin.de)`

- Michael Koch `(koch AT kde.org)`

- Christian Gebauer `(gebauer AT kde.org)`

- Simon Hausmann `(hausmann AT kde.org)`

- Glen Parker `(glenebob AT nwlink.com)`

- Scott Manson `(sdmanson AT altel.net)`

- John Firebaugh `(jfirebaugh AT kde.org)`

- Nibaldo González `(nibgonz AT gmail.com)`

Документация KatePart основана на оригинальной документации KWrite и содержит изменения, которые делают её актуальной для всех пользователей KatePart.

Автор оригинальной документации KWrite — Thad McGinnis `(ctmcginnis AT compuserve.com)`, при этом большое количество изменений внесено Christian Tibirna `(tibirna AT kde.org)`. Преобразование в формат .docbook и вычитку выполнено Lauri Watts `(lauri AT kde.org)`, а обновление — Anne-Marie Mahfouf `(annma AT kde.org)` и Anders Lund `(anders AT alweb.dk)`

Сопровождающий текущей документации KatePart — T.C. Hollingsworth `(tchollingsworth AT gmail.com)`. Чтобы отправить запрос на внесение изменений, сообщите об ошибке с помощью системы отслеживания ошибок KDE или предоставьте исправления через проект на GitLab.

Перевод на русский язык: Екатерина С. Пыжова `(haleth AT yandex.ru)`

Обновление перевода: Олег Баталов`(olegbatalov AT mail.ru)` и Виктор В. Ерёмин `(ErV2005 AT rambler.ru)`, `(erv AT box.vsi.ru)`

Редактирование перевода: Олеся Герасименко`(translation-team AT basealt.ru)`

Этот документ распространяется на условиях GNU Free Documentation License.

Программа распространяется на условиях лицензии GNU General Public License.

Глава 9. Режим ввода Vi
Режим ввода Vi

# Глава 9. Режим ввода Vi

Erlend Hamberg `<ehamberg@gmail.com>`

Перевод на русский язык: Олеся Герасименко

## Режим ввода Vi

Задача режима ввода Vi состоит не в том, чтобы полностью заменить Vim, обеспечив поддержку всех возможностей Vim. Она заключается в том, чтобы в программах, которые используют текстовый редактор KatePart в качестве встроенного, было возможно выполнять редактирование в «стиле Vim» и применять изученные приёмы работы с Vim.

Режим ввода Vi прекрасно интегрируется в сторонние программы и отклоняется от поведения Vim там, где это имеет смысл. Например, команда `:w` в режиме Vi KatePart позволяет открыть диалог сохранения.

Включить режим ввода Vi для всех новых областей просмотра возможно с помощью пункта меню Настройка → Настроить KatePart...+Редактирование → Режим ввода Vi. На этой вкладке возможно установить параметры режима ввода Vi, а также определить и отредактировать привязки клавиш. Также режим ввода Vi возможно включать или отключать с помощью пункта Режим ввода Vi в меню Правка. (Комбинация клавиш по умолчанию: Meta+Ctrl+V, где Meta обычно представляет собой клавишу Windows.)

### Примечание

В отличие от большинства комбинаций клавиш KDE, многие клавиатурные команды режима Vi зависят от регистра символов. Это означает, что команды `y` и `Y` имеют совершенно разное назначение. Чтобы ввести команду `y` (копировать), убедитесь, что режим Caps Lock отключён, и нажмите клавишу Y. Чтобы ввести команду `Y` (копировать до конца строки), воспользуйтесь комбинацией клавиш Shift+Y.

Вышеприведённое замечание не касается команд, в которых используется клавиша Ctrl. Эти команды возможно вводить независимо от состояния режима Caps Lock и без нажатия клавиши Shift. Тем не менее, для ввода некоторых команд требуется использовать Ctrl-комбинацию, за которой следует другая клавиша, регистр которой следует принимать во внимание. Например, чтобы ввести «Ctrl+W, `h`» (переключиться на левую створку в разделённой области просмотра), убедитесь, что режим Caps Lock отключён, используйте комбинацию клавиш Ctrl+W, затем отпустите эти клавиши и нажмите клавишу H.

### Расхождения с Vim

C Vim несовместимы лишь несколько функций режима ввода Vi KatePart (не принимая во внимание различные функции, которые просто не реализованы). Их перечень (с указанием соответствующих причин несовместимости) приводится далее.

- KatePart: `U` и Ctrl+R — повторное выполнение отменённой команды.

  Vim: Ctrl+R — обычное повторение действия, U — отмена всех последних изменений в одной строке.

  Клавиша U привязана к повторению отменённого действия в режиме Vi KatePart, потому что комбинация клавиш Ctrl+R по умолчанию используется для функции замены KatePart (поиск и замена). По умолчанию режим Vi не переопределяет комбинации клавиш KatePart (это возможно сделать вручную: Настройка → Настроить KatePart...+Редактирование → Режим ввода Vi), следовательно, возврат действия должен быть доступен в «обычном» режиме нажатия комбинаций клавиш. Кроме того, поведение команды `U` в Vim не очень хорошо совпадает с внутренней системой отмены KatePart, поэтому её поддержка была бы довольно сложной задачей.

- KatePart: `print` — открытие диалога Печать.

  Vim: `print` — печать строк указанного диапазона (как в ed).

  Такие команды, как `:print`, доступны не только в режиме Vi, но и в «обычном» режиме ввода KatePart. Следовательно, при использовании команды `:print` будет открыт диалог печати (соблюдается принцип однородности, а не имитируется поведение Vim).

- KatePart: `Y` — копирование данных до конца строки.

  Vim: `Y` — копирование всей строки, аналогично `y` `y`.

  Поведение команды `Y` в режиме Vi на самом деле является внутренней ошибкой. Для обеих команд, изменения и удаления, `c` `c`/ `d` `d` выполняет действие над текущей строкой, а `C`/`D` выполняет действие над данными от позиции курсора до конца строки. Но обе команды, `y` `y` и `Y`, копируют текущую строку. В режиме Vi KatePart `Y` копирует данные до конца строки. Такое поведение описывается как «более логичное» в документации Vim.

- KatePart: `O` и `o` — открытие [`количество`] новых строк и переход в режим вставки.

  Vim: `O` и `o` — открытие новой строки и вставка текста [`количество`] раз при выходе из режима вставки.

  Так сделано в результате обобщения опыта многих людей, которые выражали удивление поведением Vim на соответствующем канале в IRC (#vim на Libera Chat).

### Переключение режимов

- В обычном режиме возможно вводить команды для навигации по документу или его редактирования. Этот режим используется по умолчанию. Чтобы вернуться в этот режим из любого другого, нажмите клавишу Esc.

- Визуальный режим позволяет выделять цветом текст в документе. В этом режиме также возможно применять большинство команд обычного режима. Чтобы перейти в этот режим, нажмите клавишу `v` (для выбора символов) или `V` (для выбора строк).

- Режим вставки позволяет выполнять непосредственное редактирование документа. Чтобы перейти в этот режим, нажмите клавишу `i` или введите одну из нескольких перечисленных далее команд.

- Режим команд позволяет вызвать командную строку KatePart для выполнения значительной части команд, доступных в реализациях Vi, а также некоторых специфичных для KatePart команд. Более подробные сведения об этих командах: «Командная строка компонента редактирования». Чтобы перейти в этот режим, нажмите клавишу :, введите команду и нажмите клавишу Enter.

### Интеграция с командами Kate

- Визуальный режим автоматически включается при выборе текста с помощью мыши. Переход в этот режим также выполняется при использовании команд выбора текста Kate, например, «Выделить все» (при выборе соответствующего пункта меню или нажатии комбинации клавиш Ctrl+A).

- Предусмотрена поддержка отметок Vi и закладок Kate. Когда в режиме Vi создаётся отметка, также создаётся и соответствующая закладка Kate, доступная в меню Закладки. И наоборот: при создании закладки Kate создаётся соответствующая отметка Vi в нулевой позиции строки.

### Поддерживаемые команды обычного/визуального режимов

`a` | Перейти в режим вставки, добавлять символы после курсора
`A` | Перейти в режим вставки, добавлять символы после строки
`i` | Перейти в режим вставки, добавлять символы перед курсором
Ins | Перейти в режим вставки, добавлять символы перед курсором
`I` | Перейти в режим вставки, вставлять символы перед первым непустым символом строки
`gi` | Перейти в режим вставки, вставлять символы перед местом, в котором был совершён последний выход из режима вставки
`v` | Перейти в визуальный режим, обозначить символы
`V` | Перейти в визуальный режим, обозначить строки
Ctrl+v | Перейти в визуальный режим, обозначить блоки
`gb` | Перейти в визуальный режим, повторно обозначить последний обозначенный фрагмент
`o` | Открыть новую строку под текущей
`O` | Открыть новую строку над текущей
`J` | Объединить строки
`c` | Изменить: с определением позиции для удаления и переходом в режим вставки
`C` | Изменить до конца строки: удалить текст до конца строки и перейти в режим вставки
`cc` | Изменить строку: удалить строку и перейти в режим вставки
`s` | Заменить символ
`S` | Заменить строку
`dd` | Удалить строку
`d` | С определением позиции для удаления
`D` | Удалить до конца строки
`x` | Удалить символ справа от курсора
Del | Удалить символ справа от курсора
`X` | Удалить символ слева от курсора
`gu` | С определением позиции для перевода в нижний регистр
`guu` | Перевести текущую строку в нижний регистр
`gU` | С определением позиции для перевода в верхний регистр
`gUU` | Перевести текущую строку в верхний регистр
`y` | С определением позиции для «копирования»
`yy` | Копировать строку
`Y` | Копировать строку
`p` | Вставить после курсора
`P` | Вставить перед курсором
`]p` | Вставить после курсора с отступом
`[p` | Вставить перед курсором с отступом
`r` | С определением символа, который должен заменить символ, следующий за курсором
`R` | Перейти в режим замены
`:` | Перейти в режим команд
`/` | Поиск
`u` | Отменить
Ctrl+R | Повторить
`U` | Повторить
`m` | Установить отметку (возможно использовать для последующих определений позиции)
`n` | Найти следующее совпадение
`N` | Найти предыдущее совпадение
`>>` | Увеличить отступ строки
`<<` | Уменьшить отступ строки
`>` | Увеличить отступ строк
`<` | Уменьшить отступ строк
Ctrl+F | Страница вниз
Ctrl+B | Страница вверх
`ga` | Вывести ASCII-значение символа
`.` | Повторить последнее изменение
`==` | Команда выравнивания строки
`=` | Команда выравнивания строк
`~` | Изменить регистр текущего символа
Ctrl+S | Разделить область просмотра по горизонтали
Ctrl+V | Разделить область просмотра по вертикали
Ctrl+W, `w` | Циклический переход к следующей части разделённой области просмотра
Ctrl+W, `h` Ctrl+W Влево | Перейти к левой части разделённой области просмотра
Ctrl+W, `l` Ctrl+W Вправо | Перейти к правой части разделённой области просмотра
Ctrl+W, `k` Ctrl+W Вверх | Перейти к верхней части разделённой области просмотра
Ctrl+W, `j` Ctrl+W Вниз | Перейти к нижней части разделённой области просмотра

### Поддерживаемые команды перемещения

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

`h` | Влево
Влево | Влево
Backspace | Влево
`j` | Вниз
Вниз | Вниз
`k` | Вверх
Вверх | Вверх
`l` | Вправо
Вверх | Вправо
Пробел | Вправо
`$` | Конец строки
End | Конец строки
`0` | Первый символ в строке (позиция 0)
Home | Первый символ в строке
`^` | Первый непустой символ в строке
`f` | С определением символа, к которому следует перейти справа от курсора
`F` | С определением символа, к которому следует перейти слева от курсора
`t` | С определением символа, к которому следует перейти справа от курсора, поместив курсор на символ перед ним
`T` | С определением символа, к которому следует перейти слева от курсора, поместив курсор на символ перед ним
`gg` | Первая строка
`G` | Последняя строка
`w` | Следующее слово
`W` | Следующее слово, отделённое пробелом
`b` | Предыдущее слово
`B` | Предыдущее слово, отделённое пробелом
`e` | Конец слова
`E` | Конец слова, отделённого пробелом
`ge` | Конец предыдущего слова
`gE` | Конец предыдущего слова, отделённого пробелом
`|` | С определением номера позиции в строке для перехода
`%` | С определением элемента для перехода
``` | Отметка
`‘` | Первый непробельный символ строки с отметкой
`[[` | Предыдущая открывающая скобка
`]]` | Следующая открывающая скобка
`[]` | Предыдущая закрывающая скобка
`][` | Следующая закрывающая скобка
Ctrl+I | Перейти к следующему расположению
Ctrl+O | Вернуться к предыдущему расположению
`H` | Перейти к первой строке на экране
`M` | Перейти к строке в середине экрана
`L` | Перейти к последней строке на экране
`%`(значение в процентах)`` | Перейти к указанной в процентах позиции в документе
`gk` | Перейти на строку выше визуально (в случае использования динамического переноса строк)
`gj` | Перейти на строку ниже визуально (в случае использования динамического переноса строк)
Ctrl+Влево | Перейти на слово влево
Ctrl+Вправо | Перейти на слово вправо

### Поддерживаемые текстовые объекты

Текстовые объекты возможно использовать для выбора определённых частей документа.

`iw` | Блок слова: слово с пробелами
`aw` | Слово: слово без пробелов
`i"` | От предыдущих двойных кавычек (`"`) до следующих, включая сами кавычки
`a”` | От предыдущих двойных кавычек (`"`) до следующих, исключая сами кавычки
`i'` | От предыдущих одинарных кавычек (`'`) до следующих, включая сами кавычки
`a'` | От предыдущих одинарных кавычек (`'`) до следующих, исключая сами кавычки
`i(` | От предыдущей открывающей круглой скобки [`(`] до следующей закрывающей круглой скобки [`)`], включая сами скобки
`a(` | От предыдущей открывающей круглой скобки [`(`] до следующей закрывающей круглой скобки [`)`], исключая сами скобки
`i[` | От предыдущей открывающей квадратной скобки (`[`) до следующей закрывающей квадратной скобки (`]`), включая сами скобки
`a[` | От предыдущей открывающей квадратной скобки (`[`) до следующей закрывающей квадратной скобки (`]`), исключая сами скобки
`i{` | От предыдущей открывающей фигурной скобки (`{`) до следующей закрывающей фигурной скобки (`}`), включая сами скобки
`a{` | От предыдущей открывающей фигурной скобки (`{`) до следующей закрывающей фигурной скобки (`}`), исключая сами скобки
`i<` | От предыдущей открывающей угловой скобки (`<`) до следующей закрывающей угловой скобки (`>`), включая сами скобки
`a<` | От предыдущей открывающей угловой скобки (`<`) до следующей закрывающей угловой скобки (`>`), исключая сами скобки
`i`` | От предыдущего обратного апострофа (```) до следующего, включая сами обратные апострофы
`a`` | От предыдущего обратного апострофа (```) до следующего, исключая сами обратные апострофы

### Поддерживаемые команды режима вставки

Ctrl+D | Уменьшить отступ
Ctrl+T | Увеличить отступ
Ctrl+E | Вставить снизу
Ctrl+Y | Удалить слово
Ctrl+W | Удалить слово
Ctrl+U | Удалить строку
Ctrl+J | Новая строка
Ctrl+H | Удалить символ в обратном направлении
Ctrl+Home | Перейти к первому символу в документе
Ctrl+R `n` | Вставить содержимое регистра `n`
Ctrl+O, `команда` | Перейти в обычный режим только для одной команды
Ctrl+A | Увеличить текущее выбранное число
Ctrl+X | Уменьшить текущее выбранное число

### Текстовый объект, ограниченный запятыми

Этого объекта нет в Vim. Текстовый объект, ограниченный запятыми, упрощает изменение списков параметров на C-подобных языках и других списков, разделённых запятыми. Таким текстовым объектом является фрагмент текста между двумя запятыми или между запятой и скобкой. На снимке обозначены красным фоном три диапазона текстовых объектов.

Диапазоны текстовых объектов. Если курсор находится в пределах например `arg2`, при нажатии клавиш `ci`, («изменить между запятыми») текст `double arg2` будет удалён, а курсор — помещён между двумя запятыми в режиме вставки. Это очень удобный способ изменения параметров функции.

### Нереализованные возможности

Как было отмечено выше, задачей режима Vi KatePart не является стопроцентная поддержка возможностей Vim.

Приложение A. Регулярные выражения
Регулярные выражения

# Приложение A. Регулярные выражения

Anders Lund `<anders@alweb.dk>`

Перевод на русский язык: Андрей Балагута
Обновление перевода: Олеся Герасименко

    Это приложение содержит краткое, но достаточно ёмкое описание регулярных выражений в той форме, в которой они используются в KatePart (они не совместимы с регулярными выражениями perl и grep).

## Введение

Регулярные выражения — это средство, позволяющее описывать содержание строк в некотором формализованном виде, что позволяет приложениям определять принадлежность той или иной строки определённому формату. В дополнение ко всему некоторые приложения могут сохранять части совпавшей строки для их последующего использования.

Приведём небольшой пример. Допустим, требуется найти в тексте все абзацы, которые начинаются с фамилий «Петров» или «Иванов», за которыми следует любая форма глагола «рассказывать» (для чистоты эксперимента возьмём всего две формы: «рассказал» и «рассказывал»).

С помощью обычного поиска понадобилось бы сначала найти фамилию «Петров», возможно, дополненную буквами «рассказ», что-то вроде этого: `Петров рассказ`. При поиске совпадений пришлось бы пропускать все строки, которые стоят не в начале абзаца. После этого последовал бы повторный поиск для второй фамилии...

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

Регулярные выражения содержат правила, позволяющие точно выразить вид строки для поиска. Приведённый пример возможно выразить словесно: «Строка, начинающаяся со слов „Петров“ или „Иванов“, перед которыми могут стоять до четырёх пробелов или символов табуляции, после фамилии должен стоять пробел, за пробелом — „рассказ“, после чего может (необязательно!) стоять суффикс „ыв“, и, наконец, суффикс „ал“». Это возможно записать в форме регулярного выражения:

`^[ \t]{0,4}(Петров|Иванов) рассказ(ыв)?ал`

Этот пример демонстрирует четыре основных понятия современных регулярных выражений:

- Шаблоны

- Утверждения

- Кванторы

- Обратные ссылки

Знак `^`, с которого начинается выражение, — это утверждение, которое подтверждает совпадение только в том случае, если совпавшая цепочка символов начинается с новой строки.

`[ \t]` и `(Петров|Иванов) рассказ(ыв)?ал` — это шаблоны. Первый представляет собой символьный класс, который совпадает либо с пробелом, либо с символом табуляции. Второй содержит вложенный шаблон, совпадающий со словами `Петров` или `Иванов`, затем идёт проверка на точное совпадение со строкой `рассказ`, потом ещё один вложенный шаблон, который определяет вхождение символов `ыв`, и, в самом конце, проверка на точное совпадение с символами `ал`

Строка `{0,4}` и символ вопроса после вложенного шаблона `(ыв)` — это кванторы. Первый интерпретируется следующим образом: «возможен повтор предыдущего символа от 0 до 4 раз». Второй квантор действует аналогично, позволяя повторить стоящий перед ним вложенный шаблон 0 или 1 раз.

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

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

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

Шаблоны
Шаблоны

## Шаблоны

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

### Управляющие последовательности

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

Делается это очень просто, необходимо всего лишь поставить перед таким символом обратную черту (`\`).

Анализатор регулярных выражений игнорирует обратную черту перед символами, которые не имеют специального значения в контексте; например, если вместо обычного символа «j» ввести `\j`, анализатор будет интерпретировать его просто как «j». Таким образом, если неизвестно, имеет ли символ специальное значение, возможно без опасений предварить его обратной чертой.

Для указания собственно обратной черты (в качестве обычного символа) необходимо продублировать её: `\\`.

### Символьные классы и сокращения

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

Простые символьные классы содержат один или несколько символов, например, `[abc]` (проверка на любой из символов «a», «b» или «c») или `[0123456789]` (проверка на любую цифру).

Поскольку буквы и цифры упорядочены логически, возможно сокращать классы, используя диапазоны: `[a-c]` аналогично `[abc]`, `[0-9]` аналогично `[0123456789]`. Возможно комбинировать диапазоны с обычным перечислением символов: `[a-fynot1-38]` (проверка на любой из символов «a»,«b»,«c»,«d», «e»,«f»,«y»,«n»,«o»,«t», «1»,«2»,«3» или «8»).

Чтобы проверить символ без учёта регистра в любом случае (регулярное выражение позволяет учитывать или не учитывать регистр символов), следует написать примерно следующее: `[aAbB]`.

Возможно создать «исключающий» класс, который проверяет символ на «невхождение» в заданный набор символов. Обычный символьный класс превращается в исключающий добавлением символа «`^`» перед набором символов:

`[^abc]` — проверка на любой символ, кроме «a», «b» и «c».

В дополнение к обычным символам возможно использовать следующие сокращения:

`\a`

  Проверка на ASCII-символ звонка (BEL, 0x07).

`\f`

  Проверка на ASCII-символ перевода страницы (FF, 0x0C).

`\n`

  Проверка на ASCII-символ перевода строки (LF, 0x0A, символ перехода на новую строку в Unix).

`\r`

  Проверка на ASCII-символ возврата каретки (CR, 0x0D).

`\t`

  Проверка на ASCII-символ горизонтальной табуляции (HT, 0x09).

`\v`

  Проверка на ASCII-символ вертикальной табуляции (VT, 0x0B).

`\xhhhh`

  Проверка на символ Юникода, соответствующий шестнадцатеричному числу hhhh (в пределах 0x0000-0xFFFF). \0ooo (первый символ — ноль) — проверка на символ в кодировке ASCII/Latin-1, соответствующий восьмеричному числу ooo (в пределах 0-0377).

`.` (точка)

  Проверка на любой символ (включая переход на новую строку).

`\d`

  Проверка на цифровой символ. Аналогично классу `[0-9]`.

`\D`

  Проверка на любой символ, не являющийся цифровым. Аналогично `[^0-9]` или `[^\d]`.

`\s`

  Проверка на пробельный символ. Фактически аналогично классу `[ \t\n\r]`.

`\S`

  Проверка на любой символ, не являющийся пробельным. Фактически равнозначно `[^ \t\r\n]` и аналогично `[^\s]`.

`\w`

  Проверка на любой «словообразующий символ» (все буквы и цифры, а также символ подчёркивания). Аналогично классу `[a-zA-Z0-9_]`.

`\W`

  Проверка на любой символ, не являющийся словообразующим (все символы, кроме букв, цифр и подчёркиваний). Аналогично классу `[^a-zA-Z0-9_]` или `[^\w]`.

Нотация классов POSIX, `[:<имя класса>:]`, также поддерживается. Например, `[:digit:]` аналогично `\d`, а `[:space:]` — `\s`. Полный перечень символьных классов POSIX доступен здесь.

Аббревиатурные классы возможно помещать в обычные классы; например, чтобы выполнить проверку на словообразующий символ, точку или пробел, возможно ввести следующее: `[\w \.]`

#### Символы со специальным значением в символьных классах

Далее перечислены символы, имеющие специальное значение в определениях символьных классов («[]»). Для использования в качестве обычных символов они должны быть предварены обратной чертой.

`]`

  Закрывает символьный класс. Этот символ должен быть предварён обратной чертой, кроме тех случаев, когда он находится непосредственно в начале класса или сразу после символа `^`.

`^`

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

`-` (дефис)

  Объявляет логический диапазон. При использовании внутри символьного класса этот символ всегда следует предварять обратной чертой.

`\` (обратная черта)

  Спецсимвол (escape character). Чтобы использовать его как обычный символ, продублируйте.

### Альтернативы: проверка на «один из» нескольких шаблонов

Если требуется выполнить проверку на один (любой) шаблон из определённого набора, используйте альтернативы. Чтобы объявить альтернативу, следует все шаблоны набора записать через вертикальную черту (`|`).

Например, чтобы найти любое из имён «Вася» и «Петя», необходимо использовать такое выражение: `Вася|Петя`.

### Вложенные шаблоны

Вложенными называются шаблоны, заключённые в круглые скобки. Они используются в разных целях:

#### Определение альтернатив

С помощью вложенных шаблонов возможно группировать набор альтернатив внутри сложных шаблонов. Альтернативы разделяются символом вертикальной черты («|»).

Например, чтобы найти одно из слов «int», «float» или «double», возможно использовать шаблон `int|float|double`. Если же требуется найти одно из этих слов, за которым следуют пробелы, а за ними — какие-то символы, то необходимо оформить альтернативу как вложенный шаблон: `(int|float|double)\s+\w+`.

#### Захват совпавшего текста (обратные ссылки)

Вложенный шаблон `(ШАБЛОН)` позволяет использовать обратную ссылку благодаря запоминанию нужной части шаблона. Чтобы не выполнялось запоминание вложенного шаблона, необходимо использовать группу без захвата `(?:ШАБЛОН)`.

Например, если требуется найти два одинаковых слова, разделённых запятой и, возможно, пробелами, возможно использовать такое выражение: `(\w+),\s*\1`. Вложенный шаблон `\w+` выполняет поиск цепочки словообразующих символов, а всё выражение выполняет поиск той же цепочки, за которой следует запятая, далее могут идти пробелы, а за ними — точно такая же цепочка (строка `\1` ссылается на первый вложенный шаблон, заключённый в круглые скобки).

### Примечание

Чтобы избежать неясности при использовании символов `\1`, за которыми следуют цифры (например, `\12` может являться двенадцатым вложенным шаблоном или просто первым вложенным шаблоном с цифрой `2`), вложенные шаблоны, состоящие из нескольких цифр, указываются в формате `\{12}`.

Примеры:

- `\{12}1` = «использовать вложенный шаблон 12»

- `\123` = «запомнить 1, а 23 — обычный текст»

#### Утверждения просмотра вперёд

Утверждение просмотра вперёд — это вложенный шаблон, который начинается с символов `?=` или `?!`.

Например, чтобы найти слово «Билл», за которым может следовать что угодно, кроме слова « Гейтс», следует составить такое выражение: `Билл(?! Гейтс)` (оно совпадёт с «Билл Клинтон», «Билли хороший мальчик», но не с именем известного магната).

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

Смотрите также раздел Утверждения.

#### Утверждения просмотра назад

Утверждение просмотра назад — это вложенный шаблон, который начинается с символов `?<=` или `?<!`.

Утверждение просмотра назад работает так же, как и утверждение просмотра вперёд, отличие лишь в направлении просмотра. Например, чтобы найти слово «град», которому не предшествуют символы «вино», следует использовать следующее выражение: `(?<!вино)град`.

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

Смотрите также раздел Утверждения.

### Символы со специальным значением в шаблонах

Следующие символы имеют специальное значение в шаблонах, поэтому, чтобы использовать их в качестве обычных символов, необходимо впереди ставить обратную черту:

`\` (обратная черта)

  С этого символа должны начинаться все спецсимволы.

`^`

  Проверка на начало строки.

`$`

  Проверка на конец строки.

`()` (левая и правая круглые скобки)

  Объявление вложенного шаблона.

`{}` (левая и правая фигурные скобки)

  Объявление численного квантора.

`[]` (левая и правая квадратные скобки)

  Объявление символьного класса.

`|` (вертикальная черта)

  Логическое ИЛИ. Используется для разделения альтернатив.

`+` (плюс)

  Квантор «один или более».

`*` (звёздочка)

  Квантор «ноль или более».

`?` (знак вопроса)

  Необязательный символ. Можно считать его квантором «ноль или один».

Кванторы
Кванторы

## Кванторы

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

Кванторы записываются в фигурных скобках (`{` и `}`). Общий вид квантора: `{[минимальное-количество-совпадений][,[максимальное-количество-совпадений]]}`

Использование кванторов лучше пояснить на примерах:

`{1}`

  Ровно одно появление

`{0,1}`

  Ноль или одно появление

`{,1}`

  То же самое, только короче.

`{5,10}`

  Как минимум 5 повторений, максимум — 10.

`{5,}`

  Как минимум 5 повторений (без верхней границы).

Также определены несколько сокращений:

`*` (звёздочка)

  аналогично `{0,}`, найти любое количество повторений (вплоть до нуля повторений).

`+` (плюс)

  аналогично `{1,}`, как минимум одно появление.

`?` (знак вопроса)

  аналогично `{0,1}`, ноль или одно появление.

### Жадность

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

Современные анализаторы позволяют определять как жадные, так и нежадные регулярные выражения. В основном это проявляется в соответствующих элементах графического интерфейса, например, в диалоге поиска может присутствовать опция «Минимальное совпадение».

### Примеры использования

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

`^\d{4,5}\s`

  Совпадёт с «1234 вперед» и «12345 стоп», но не совпадёт ни с «567 восемь», ни с «223459 много».

`\s+`

  Проверка на один или более пробельных символов.

`(ля){1,}`

  Совпадёт с «ляляля» и с подстрокой «ля» в словах «кляча» и «земля».

`/?>`

  Совпадёт с «/>» в «<closeditem/>», а также с «>» в строке «<openitem>».

Утверждения
Утверждения

## Утверждения

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

Утверждение не проверяет символы, скорее, оно анализирует совпавшую строку перед тем как подтвердить совпадение. Например, утверждение граница слова не пытается найти символ-разделитель слов, наоборот, оно проверяет, что в данной позиции нет словообразующего символа. Это означает, что утверждение будет верно даже в случае отсутствия символа-разделителя, например, в конце строки поиска.

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

Регулярные выражения, описанные в этом руководстве, поддерживают следующие утверждения:

`^` (начало строки)

  Проверка на начало строки.

  Выражение `^Пётр` совпадёт с «Пётр» в строке «Пётр, здравствуйте!», но не в строке «Здравствуйте, Пётр!».

`$` (конец строки)

  Проверка на конец строки поиска.

  Выражение `ты\?$` совпадёт с последним «ты» в строке «— Ты не сделаешь этого! — А ты?», но не совпадёт ни с какой частью строки «Ты не сделал этого, так?».

`\b` (граница слова)

  Проверяет, есть ли в данном месте с одной стороны словообразующий символ, а с другой — отличный от словообразующего (необязательно разделитель!).

  Это утверждение используется для поиска границ слов; например, можно использовать два таких утверждения, чтобы найти целое слово. Выражение `\bиз\b` совпадёт с отдельным словом «из» во фразе «Он выпал из этого окна, хорошо хоть, что тут низко», но не совпадёт с «из» в слове «низко».

`\B` (нет границы слова)

  Действие этого утверждения обратно утверждению «\b».

  Это значит, что данное утверждение будет совпадать, например, в середине слова: выражение `\Bце\B` совпадёт с «це» в строке «сцена», но не в «целое».

`(?=ШАБЛОН)` (подтверждающий просмотр вперёд)

  Утверждения просмотра вперёд действуют аналогично обычным шаблонам, с той лишь разницей, что текст, совпавший (или не совпавший, в зависимости от типа просмотра) с утверждением, не будет включен в результирующее совпадение. Подтверждающий просмотр вперёд проверяет текст на предмет совпадения с ШАБЛОНОМ утверждения.

  Выражение `программ(?=\w)` совпадёт с «программ» в слове «программист», но не во фразе «Он написал много хороших программ!».

`(?!ШАБЛОН)` (отрицающий просмотр вперёд)

  Отрицающий просмотр вперёд проверяет текст на предмет несовпадения с ШАБЛОНОМ.

  Выражение `const \w+\b(?!\s*&)` совпадёт с «const char» в строке «const char* foo», но не совпадёт с «const QString» в «const QString& bar», поскольку «&» совпадает с шаблоном отрицающего просмотра вперёд.

`(?<=ШАБЛОН)` (подтверждающий просмотр назад)

  Утверждения просмотра назад действуют аналогично утверждениям просмотра вперёд, разница заключается только в направлении просмотра. Утверждение просмотра назад проверяет часть строки, которая предшествует возможному совпадению. Подтверждающее утверждение просмотра назад будет совпадать со строкой только в том случае, если ей предшествует ШАБЛОН утверждения, но найденное совпадение не будет включено в результат.

  Выражение `(?<=цвет)ок` совпадёт с «ок», если этим символам предшествуют символы «цвет» (в слове «цветок», но не в слове «росток» или в отдельном слове «ок»).

`(?<!ШАБЛОН)` (отрицающий просмотр назад)

  Отрицающий просмотр назад проверяет текст на предмет несовпадения с ШАБЛОНОМ.

  Выражение `(?<![\w\.])[0-9]+` совпадёт с «123» в строках «=123» и «-123», но не совпадёт с «123» в строках «.123» и «слово123».

`(ШАБЛОН)` (захватываемая группа)

  Вложенный шаблон в круглых скобках будет захвачен и запомнен, что позволяет использовать его в обратных ссылках. Например, выражение `(&quot;+)[^&quot;]*\1` совпадает с `""""текст""""` и `"текст"`.

  Подробные сведения доступны в разделе Захват совпавшего текста (обратные ссылки).

`(?:ШАБЛОН)` (группа без захвата)

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