<chapter id="dev">
<chapterinfo>
<authorgroup>
<author
>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author>
<othercredit role="translator"
><firstname
>Юрій</firstname
><surname
>Чорноіван</surname
><affiliation
><address
><email
>yurchor@ukr.net</email
></address
></affiliation
><contrib
>Переклад українською</contrib
></othercredit
> 
</authorgroup>
</chapterinfo>
<title
>Розширення можливостей &katepart;</title>

<sect1 id="dev-intro">
<title
>Вступ</title>

<para
>Подібно до всіх компонентів текстових редакторів з широкими можливостями, у &katepart; передбачено певні шляхи до розширення функціональних можливостей компонента. Ви можете <link linkend="dev-scripting"
>створювати прості скрипти, що реалізують додаткові можливості, за допомогою JavaScript</link
>. Нарешті, вдосконаливши ваш екземпляр &katepart;, ви можете <ulink url="http://kate-editor.org/join-us/"
>долучитися до розробників</ulink
> і поділитися вашими удосконаленнями з іншими користувачами!</para>

</sect1>

<sect1 id="highlight">
<title
>Як працювати з підсвічуванням синтаксису</title>

<sect2 id="highlight-overview">

<title
>Огляд</title>

<para
>Підсвічування синтаксису призначено для автоматично показу тексту у різних стилях і кольорах, залежно від призначення відповідного рядка та файла, з якого взято цей рядок. У початковому коді програми, наприклад, оператори керування може бути показано жирним шрифтом, а типи даних і коментарі — кольором, відмінним від кольору решти тексту. За допомогою підсвічування можна значно покращити зручність читання тексту, а отже підвищити ефективність та продуктивність роботи з цим текстом.</para>

<mediaobject>
<imageobject
><imagedata format="PNG" fileref="highlighted.png"/></imageobject>
<textobject
><phrase
>Функція, написана мовою Perl, показана з підсвічуванням синтаксису.</phrase
></textobject>
<caption
><para
>Функція, написана мовою Perl, показана з підсвічуванням синтаксису.</para>
</caption>
</mediaobject>

<mediaobject>
<imageobject
><imagedata format="PNG" fileref="unhighlighted.png"/></imageobject>
<textobject
><phrase
>Та сама функція, написана мовою Perl, без підсвічування.</phrase
></textobject>
<caption
><para
>Та сама функція, написана мовою Perl, без підсвічування.</para
></caption>
</mediaobject>

<para
>Ну що, який з двох прикладів зручніше читати?</para>

<para
>У &kappname; передбачено гнучку, придатну для налаштування і потужну систему підсвічування синтаксичних конструкцій, у стандартному пакунку ви знайдете визначення для широкого спектру мов програмування, написання скриптів та розмітки, а також текстових файлів у інших форматах. Окрім того, ви можете створювати власні визначення за допомогою простих файлів &XML;.</para>

<para
>&kappname; автоматично визначатиме належні правила підсвічування синтаксису під час відкриття файла. Дія з визначення відбуватиметься на основі типу &MIME; файла, який визначатиметься за суфіксом назви файла або, якщо у назві немає суфіксу, за вмістом файла. Якщо, на вашу думку, програма зробила неправильний вибір, ви можете вручну вказати правила підсвічування за допомогою пункту меню <menuchoice
><guimenu
>Інструменти</guimenu
> <guisubmenu
>Підсвічування</guisubmenu
></menuchoice
>.</para>

<para
>Гарнітури шрифту та кольори, які буде використано визначенням підсвічування синтаксису, можна налаштувати на вкладці <link linkend="prefcolors-highlighting-text-styles"
>Стилі підсвічування тексту</link
> <link linkend="config-dialog"
>діалогового вікна налаштування</link
>, типами ж &MIME; та суфіксами назв файлів, для яких буде використано таке підсвічування керує вкладка <link linkend="pref-open-save-modes-filetypes"
>Режими та типи файлів</link
>.</para>

<note>
<para
>Підсвічування можна використовувати для покращення візуального сприйняття тексту, але довірятися підсвічуванню під час перевірки коректності синтаксису тексту не слід. Синтаксична розмітка тексту є непростим завданням, складність якого залежить від формату тексту, — у деяких випадках, автори синтаксичних правил вважають успіхом правильний показ 98% тексту, хоча для того, щоб побачити 2% тексту з неправильним підсвічуванням, вам доведеться скористатися не дуже поширеним стилем.</para>
</note>

<tip>
<para
>Ви можете отримати оновлені або додаткові правила визначення підсвічування синтаксису з вебсайта &kappname;. Для цього вам слід натиснути кнопку <guibutton
>Отримати файли підсвічування...</guibutton
> на вкладці <link linkend="pref-open-save-modes-filetypes"
>Режими та типи файлів</link
> <link linkend="config-dialog"
>діалогового вікна налаштування</link
>.</para>
</tip>

</sect2>

<sect2 id="katehighlight-system">

<title
>Система підсвічування синтаксису &kappname;</title>

<para
>У цьому розділі ми зосередимося на механізмах, які використовуються для підсвічування синтаксису у &kappname;. Відомості з цього розділу призначено для тих користувачів, яким цікаво дізнатися про роботу системи підсвічування синтаксису, або тих користувачів, які бажають змінити або створити нові визначення підсвічування синтаксису.</para>

<sect3 id="katehighlight-howitworks">

<title
>Як це працює</title>

<para
>Під час відкриття файла однією з перших дій, які виконує редактор &kappname;, є визначення правил підсвічування синтаксису для цього файла. Під час читання тексту з файла або отримання введених вами рядків система підсвічування синтаксису аналізуватиме текст на основі правил підсвічування синтаксису і позначатиме у показаному тексті позиції початку і завершення різних контекстів і стилів.</para>

<para
>Під час введення документа за допомогою клавіатури створений вами текст буде проаналізовано і розмічено на льоту, отже, якщо ви вилучите символ, які система розмітила як початок або завершення певного контексту, стиль сусідніх з поточним фрагментів тексту також змінюватиметься відповідно до зміни контексту.</para>

<para
>Визначення синтаксичних правил, які використовуються у системі підсвічування синтаксису &kappname;, є файлами &XML;, у яких містяться <itemizedlist>
<listitem
><para
>Правила для визначення ролі тексту, впорядковані у контекстні блоки</para
></listitem>
<listitem
><para
>Списки ключових слів</para
></listitem>
<listitem
><para
>Визначення елементів стилю</para
></listitem>
</itemizedlist>
</para>

<para
>Під час аналізу тексту правила визначення контексту застосовуватимуться у порядку, у якому ці правила було визначено у файлі визначень, — якщо початок поточного рядка відповідає певному правилу, буде використано відповідний контекст. Після цього початкову точку у тексті буде пересунуто у завершальну точку застосування визначеного правила і почнеться новий цикл пошуку відповідників правил в межах контексту, встановленого попереднім правилом.</para>

</sect3>

<sect3 id="highlight-system-rules">
<title
>Правила</title>

<para
>Правила визначення є основою системи визначення підсвічування. Кожне правило визначається рядком, символом або <link linkend="regular-expressions"
>формальним виразом</link
>, з яким порівнюватиметься текст документа. Правилом визначаються відомості, які буде використано під час визначення стилю відповідного фрагмента тексту. Правило може перемкнути поточний контекст системи підсвічування або на явно вказаний у правилі контекст або на попередній контекст, який було використано у тексті.</para>

<para
>Правила об’єднуються у контекстні групи. Кожна контекстна група реалізує основні елементи у відповідному форматі файлів, наприклад текстові рядки у лапках або блоки коментарів у файлах кодів програми. За такої структури системи підсвічування можна уникнути потреби у переборі всього набору правил, коли такий перебір не потрібен, а також мати можливість різного трактування деяких послідовностей символів у тексті, залежно від поточного контексту. </para>

<para
>Контексти можуть створюватися і динамічно, таким чином забезпечується використання у правилах особливостей даних документа.</para>

</sect3>

<sect3 id="highlight-context-styles-keywords">
<title
>Контекстні стилі і ключові слова</title>

<para
>У деяких мовах програмування цілі числа обробляються компілятором (програмою, яка перетворює початкові коди програми на бінарний файл програми) у спосіб, відмінний від способу обробки чисел з плаваючою крапкою, також у рядках, взятих у лапки, можуть бути символи зі спеціальним призначенням. У таких випадках було б доцільним виокремити подібні символи, щоб їх простіше було виявити під час читання коду. Отже, навіть якщо ці символи не мають окремого контексту, система підсвічування тексту показати їх так, неначе подібний контекст для них існує, тобто виокремити їх з-поміж навколишнього тексту.</para>

<para
>У визначенні синтаксису може бути довільна кількість стилів, достатня для визначення всіх елементів формату тексту, для якого це визначення було створено.</para>

<para
>У багатьох форматах існують списки слів, які відповідають певному елементу. Наприклад, у мовах програмування керівні команди складають один елемент, назви типів даних — другий, вбудовані функції мови — третій. Система підсвічування синтаксису &kappname; здатна використовувати такі списки для виявлення і позначення слів у тексті з метою підкреслення призначення елементів у текстових форматах.</para>

</sect3>

<sect3 id="kate-highlight-system-default-styles">
<title
>Типові стилі</title>

<para
>Якщо ви відкриєте файл кодів мовою C++, &Java; або документ <acronym
>HTML</acronym
> у &kappname;, ви переконаєтеся у тому, що, хоча формати цих файлів є різними, а отже у них використовуються різні слова для позначень елементів тексту, кольори, які буде використано програмою будуть тими самими. Причиною цього є існування у &kappname; наперед визначеного списку типових стилів, який використовується у окремих визначеннях синтаксису.</para>

<para
>Типові стилі спрощують розпізнавання подібних елементів у різних форматах тексту. Наприклад, коментарі передбачено майже у всіх мовах програмування, написання скриптів або мовах розмітки, отже, якщо їх буде показано у однаковому стилі у всіх форматах мов, вам не потрібно буде зупинятися і розмірковувати над тим, як виглядають коментарі у тексті документа.</para>

<tip>
<para
>Під час створення всіх стилів визначення синтаксису використовують один з типових стилів. У деякій частині визначень синтаксису використовуються додаткові стилі, яких немає серед типових, отже, якщо ви часто працюєте з файлами у таких форматах, доцільно відкрити діалогове вікно налаштування, щоб подивитися, чи не використовуються для певних елементів однакові стилі. Наприклад, існує лише один типовий стиль для рядків, але, оскільки у мові програмування Perl існує два типи рядків, ви можете налаштувати підсвічування для кожного з цих типів трохи по-різному. Огляд всіх <link linkend="kate-highlight-default-styles"
>можливих типових стилів</link
> буде наведено далі.</para>
</tip>

</sect3>

</sect2>

<sect2 id="katehighlight-xml-format">
<title
>Формат &XML; визначення підсвічування</title>

<sect3>
<title
>Огляд</title>

<para
>У &kappname; використовується бібліотека підсвічування синтаксичних конструкцій з &kde-frameworks;. Типово, до бібліотеки підсвічування синтаксичних конструкцій &kappname; включено засоби підсвічування коду xml. </para>

<para
>Цей розділ присвячено огляду формату &XML; визначення підсвічування. За допомогою невеличкого прикладу у розділі описано основні компоненти, їх призначення і використання. Далі ми докладно розглянемо правила визначення підсвічування синтаксису.</para>

<para
>Формальне визначення, також відоме як <acronym
>XSD</acronym
>, зберігається у <ulink url="https://commits.kde.org/syntax-highlighting?path=data/schema"
>сховищі підсвічування синтаксису</ulink
> у файлі <filename
>language.xsd</filename
>. </para>

<para
>Нетипові файли <filename class="extension"
>.xml</filename
> підсвічування синтаксису зберігаються у <filename class="directory"
>org.kde.syntax-highlighting/syntax/</filename
> у теці вашого користувача, у підтеці, назву якої можна визначити за допомогою команди <userinput
><command
>qtpaths</command
><option
>--paths GenericDataLocation</option
></userinput
>, зазвичай <filename class="directory"
><envar
>$HOME</envar
>/.local</filename
>. </para>

<para
>У &Windows; ці файли зберігаються у <filename
>%USERPROFILE%/AppData/Local/org.kde.syntax-highlighting/syntax</filename
>. <replaceable
>%USERPROFILE%</replaceable
> зазвичай є скороченням від <filename
>C:\\Users\\<replaceable
>користувач</replaceable
></filename
>.</para>

<variablelist>
<title
>Головні розділи файлів визначення підсвічування &kappname;</title>

<varlistentry>
<term
>Файл підсвічування містить заголовок, у якому встановлюється версія XML:</term>
<listitem>
<programlisting
>&lt;?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?&gt;
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term
>Кореневим елементом файла визначення є елемент <userinput
>language</userinput
>. Серед можливих атрибутів:</term>

<listitem>
<para
>Обов’язкові атрибути:</para>
<para
><userinput
>name</userinput
> визначає назву мови. Цю назву буде згодом показано у пунктах меню та діалогових вікнах програми.</para>
<para
><userinput
>section</userinput
> визначає категорію.</para>
<para
><userinput
>extensions</userinput
> визначає суфікси назв файлів, на зразок &quot;*.cpp;*.h&quot;</para>
<para
><userinput
>version</userinput
> визначає поточну модифікацію файла визначень у форматі цілого числа. Кожного разу, коли ви вноситимете зміни до файла визначень правил підсвічування, вам слід збільшувати це число.</para>
<para
><userinput
>kateversion</userinput
> визначає найостаннішу з підтримуваних версій &kappname;.</para>

<para
>Необов’язкові атрибути:</para>
<para
><userinput
>mimetype</userinput
> прив’язує файли на основі типу &MIME;.</para>
<para
><userinput
>casesensitive</userinput
> визначає, чи розрізнятимуться ключові слова за регістром символів, чи ні.</para>
<para
><userinput
>priority</userinput
> потрібно вказати, якщо у іншому файлі визначення підсвічування використовуються ті самі суфікси файлів. Для підсвічування буде використано правила з вищим пріоритетом.</para>
<para
><userinput
>author</userinput
> повинен містити ім’я і адресу електронної пошти автора.</para>
<para
><userinput
>license</userinput
> повинен містити назву ліцензії нового файла підсвічування, зазвичай, MIT.</para>
<para
><userinput
>style</userinput
> має містити дані щодо мови програмування і використовується засобами додавання відступів для атрибута <literal
>required-syntax-style</literal
>.</para>
<para
><userinput
>hidden</userinput
> визначає, чи має бути показано назву підсвічування у меню &kappname;.</para>
<para
>Отже, наступний рядок має виглядати десь так:</para>
<programlisting
>&lt;language name=&quot;C++&quot; version=&quot;1&quot; kateversion=&quot;2.4&quot; section=&quot;Sources&quot; extensions=&quot;*.cpp;*.h&quot; /&gt;
</programlisting>
</listitem>
</varlistentry>


<varlistentry>
<term
>Наступним елементом є <userinput
>highlighting</userinput
>, у цьому елементі міститься необов’язковий елемент <userinput
>list</userinput
> і обов’язкові елементи <userinput
>contexts</userinput
> і <userinput
>itemDatas</userinput
>.</term>
<listitem>
<para
>Елементи <userinput
>list</userinput
> містять список ключових слів. У цьому випадку ключовими словами будуть <emphasis
>class</emphasis
> і <emphasis
>const</emphasis
>. У разі потреби ви можете додати довільну кількість списків.</para>
<para
>У елементі <userinput
>contexts</userinput
> містяться всі контексти. Типово, першим контекстом є початок діапазону підсвічування. У контексті <emphasis
>Normal Text</emphasis
> існує два правила: перше визначає список ключових слів з назвою <emphasis
>somename</emphasis
> і правило для визначення лапок і перемикання контексту на контекст <emphasis
>string</emphasis
>. Докладніше правила буде розглянуто у наступній главі.</para>
<para
>Третя частина складається з елемента <userinput
>itemDatas</userinput
>. У цьому елементі містяться всі кольори і гарнітури шрифтів, потрібні для контекстів і правил. У нашому випадку було використано <userinput
>itemData</userinput
> <emphasis
>Normal Text</emphasis
>, <emphasis
>String</emphasis
> і <emphasis
>Keyword</emphasis
>. </para>
<programlisting
>&lt;highlighting&gt;
    &lt;list name=&quot;somename&quot;&gt;
      &lt;item&gt; class &lt;/item&gt;
      &lt;item&gt; const &lt;/item&gt;
    &lt;/list&gt;
    &lt;contexts&gt;
      &lt;context attribute=&quot;Normal Text&quot; lineEndContext=&quot;#pop&quot; name=&quot;Normal Text&quot; &gt;
        &lt;keyword attribute=&quot;Keyword&quot; context=&quot;#stay&quot; String=&quot;somename&quot; /&gt;
        &lt;DetectChar attribute=&quot;String&quot; context=&quot;string&quot; char=&quot;&amp;quot;&quot; /&gt;
      &lt;/context&gt;
      &lt;context attribute=&quot;String&quot; lineEndContext=&quot;#stay&quot; name=&quot;string&quot; &gt;
        &lt;DetectChar attribute=&quot;String&quot; context=&quot;#pop&quot; char=&quot;&amp;quot;&quot; /&gt;
      &lt;/context&gt;
    &lt;/contexts&gt;
    &lt;itemDatas&gt;
      &lt;itemData name=&quot;Normal Text&quot; defStyleNum=&quot;dsNormal&quot; /&gt;
      &lt;itemData name=&quot;Keyword&quot; defStyleNum=&quot;dsKeyword&quot; /&gt;
      &lt;itemData name=&quot;String&quot; defStyleNum=&quot;dsString&quot; /&gt;
    &lt;/itemDatas&gt;
  &lt;/highlighting&gt;
</programlisting>
</listitem>
</varlistentry>

<varlistentry>
<term
>Останньою частиною визначення підсвічування є необов’язковий розділ <userinput
>general</userinput
>. У ньому можуть міститися відомості щодо ключових слів, згортання коду, коментарів і відступів.</term>

<listitem>
<para
>У розділі <userinput
>comment</userinput
> визначається послідовність символів, за допомогою якої можна додати однорядковий коментар. Крім того, ви можете визначати багаторядкові коментарі за допомогою елемента <emphasis
>multiLine</emphasis
> з додатковим атрибутом <emphasis
>end</emphasis
>. Ці визначення буде використано за виконання користувачем дій <emphasis
>закоментувати/розкоментувати</emphasis
>.</para>
<para
>У розділі <userinput
>keywords</userinput
> визначається те, чи слід враховувати регістр символів у списку ключових слів, чи ні. Інші атрибути буде описано далі за текстом.</para>
<programlisting
>&lt;general&gt;
    &lt;comments&gt;
      &lt;comment name="singleLine" start="#"/&gt;
    &lt;/comments&gt;
    &lt;keywords casesensitive="1"/&gt;
  &lt;/general&gt;
&lt;/language&gt;
</programlisting>
</listitem>
</varlistentry>

</variablelist>


</sect3>

<sect3 id="kate-highlight-sections">
<title
>Докладно про розділи</title>
<para
>У цій частині описано всі доступні атрибути для контекстів, itemDatas, ключових слів, коментарів, згортання коду і відступів.</para>

<variablelist>
<varlistentry>
<term
>Елемент <userinput
>context</userinput
> належить до групи <userinput
>contexts</userinput
>. Цей елемент визначає специфічні для контексту правила, на зразок того, що має трапитися, якщо система підсвічування досягне кінця рядка. Серед можливих атрибутів:</term>


<listitem>
<para
><userinput
>name</userinput
> — назва контексту. За допомогою цієї назви правила визначатимуть контекст, на який слід перемкнутися у випадку виявлення відповідника правила.</para>
<para
><userinput
>lineEndContext</userinput
> визначає контекст, на який має перемкнутися система підсвічування у разі досягнення кінця рядка. Значенням може бути назва іншого контексту, <userinput
>#stay</userinput
> означатиме, що контекст не слід перемикати (тобто нічого не робити) or <userinput
>#pop</userinput
> означатиме, що слід вийти з контексту. Наприклад, можна скористатися значенням <userinput
>#pop#pop#pop</userinput
> для того, щоб система після виходу піднялася на три контексти вище, або навіть <userinput
>#pop#pop!ІншийКонтекст</userinput
>, щоб піднятися на два контексти вище і перемкнутися на контекст з назвою <userinput
>ІншийКонтекст</userinput
>.</para>
<para
><userinput
>lineEmptyContext</userinput
> визначає контекст, якщо буде знайдено порожній рядок. Типове значення: #stay.</para>
<para
><userinput
>fallthrough</userinput
> вказує, чи слід системі підсвічування перемикатися на контекст вказаний параметром fallthroughContext, якщо текст не відповідає жодному з правил. Типове значення: <emphasis
>false</emphasis
>.</para>
<para
><userinput
>fallthroughContext</userinput
> визначає наступний контекст, якщо не буде знайдено відповідника до правил.</para>
<para
><userinput
>dynamic</userinput
>: якщо має значення <emphasis
>true</emphasis
>, контекст запам’ятовуватиме рядки або заповнювачі, збережені за допомогою динамічних правил. Це потрібно, наприклад, для документів HERE. Типове значення: <emphasis
>false</emphasis
>.</para>
</listitem>
</varlistentry>


<varlistentry>
<term
>Елемент <userinput
>itemData</userinput
> знаходиться у групі <userinput
>itemDatas</userinput
>. За його допомогою визначаються тип шрифту і кольори. Таким чином можна визначати власні типи шрифтів і кольори, але ми рекомендуємо, за можливості, використовувати лише типові стилі так, щоб користувач завжди бачив однакові кольори у файлах різних форматів. Все ж іноді іншого способу не існує, і вам доведеться змінити колір і атрибути шрифту. Обов’язковими атрибутами є name і defStyleNum, інші атрибути є необов’язковими. Серед можливих атрибутів:</term>

<listitem>
<para
><userinput
>name</userinput
> визначає назву itemData. Цю назву буде використано у контекстах і правилах для посилання на itemData у атрибуті <emphasis
>attribute</emphasis
>.</para>
<para
><userinput
>defStyleNum</userinput
> визначає, який тип слід використовувати типово. Докладний перелік можливих типових стилів ви знайдете нижче.</para>
<para
><userinput
>color</userinput
> визначає колір. Можливі формати: '#rrggbb' і '#rgb'.</para>
<para
><userinput
>selColor</userinput
> визначає колір виділеного тексту.</para>
<para
><userinput
>italic</userinput
>, якщо має значення <emphasis
>true</emphasis
>, шрифт буде курсивним.</para>
<para
><userinput
>bold</userinput
>, якщо має значення <emphasis
>true</emphasis
>, шрифт тексту буде напівжирним.</para>
<para
><userinput
>underline</userinput
>: якщо цей атрибут має значення <emphasis
>true</emphasis
>, текст буде підкреслено.</para>
<para
><userinput
>strikeout</userinput
>, якщо цей параметр має значення <emphasis
>true</emphasis
>, текст буде перекреслено.</para>
<para
><userinput
>spellChecking</userinput
>: якщо цей атрибут має значення <emphasis
>true</emphasis
>, правопис тексту буде перевірено.</para>
</listitem>
</varlistentry>


<varlistentry>
<term
>Елемент <userinput
>keywords</userinput
> у групі <userinput
>general</userinput
> визначає властивості ключових слів. Серед можливих атрибутів:</term>

<listitem>
<para
><userinput
>casesensitive</userinput
>, може приймати значення <emphasis
>true</emphasis
> або <emphasis
>false</emphasis
>. Якщо має значення <emphasis
>true</emphasis
>, пошук ключових слів відбуватиметься з врахуванням регістру символів.</para>
<para
><userinput
>weakDeliminator</userinput
> — це список символів, які не є символами відокремлення слів. Наприклад, крапка <userinput
>«.»</userinput
> є символом відокремлення слів. Припустімо тепер, що ключове слово у <userinput
>list</userinput
> містить крапку, тоді це слово буде задіяно, лише якщо ви вкажете крапку серед значень цього аргументу.</para>
<para
><userinput
>additionalDeliminator</userinput
> визначає додаткові символи розмітки.</para>
<para
><userinput
>wordWrapDeliminator</userinput
> визначає символи, після яких можна розривати рядок.</para>
<para
>Типовими символами розмітки і символами відокремлення слів є символи <userinput
>.():!+,-&lt;=&gt;%&amp;*/;?[]^{|}~\</userinput
>, пробіл (<userinput
>' '</userinput
>) і символ табуляції (<userinput
>'\t'</userinput
>).</para>
</listitem>
</varlistentry>


<varlistentry>
<term
>Елемент <userinput
>comment</userinput
> у групі <userinput
>comments</userinput
> визначає властивості коментаря, які буде використано для дій за пунктами меню <menuchoice
><guimenu
>Інструменти</guimenu
> <guimenuitem
>Закоментувати</guimenuitem
></menuchoice
> і <menuchoice
><guimenu
>Інструменти</guimenu
> <guimenuitem
>Розкоментувати</guimenuitem
></menuchoice
>. Серед доступних атрибутів:</term>

<listitem>
<para
><userinput
>name</userinput
>: може мати значення <emphasis
>singleLine</emphasis
> або <emphasis
>multiLine</emphasis
>. Якщо буде обрано варіант <emphasis
>multiLine</emphasis
>, слід буде також вказати атрибути <emphasis
>end</emphasis
> і <emphasis
>region</emphasis
>.</para>
<para
><userinput
>start</userinput
> визначає рядок, який використовується для позначення початку коментаря. У C++ цим рядком є &quot;/*&quot;.</para>
<para
><userinput
>end</userinput
> визначає рядок, яким завершуватиметься коментар. У C++ цим рядком буде &quot;*/&quot;.</para>
<para
>Атрибут <userinput
>region</userinput
> повинен мати значення назви придатного для згортання багаторядкового коментаря. Припустімо, що у правилах вказано <emphasis
>beginRegion="Comment"</emphasis
> ... <emphasis
>endRegion="Comment"</emphasis
>, тоді вам слід взяти значення <emphasis
>region="Comment"</emphasis
>. За допомогою цього атрибута можна користуватися дією з розкоментування, навіть якщо було виділено не весь текст багаторядкового коментаря. Потрібно лише, щоб курсор знаходився всередині цього багаторядкового коментаря.</para>
</listitem>
</varlistentry>


<varlistentry>
<term
>Елемент <userinput
>folding</userinput
> у групі <userinput
>general</userinput
> призначено для визначення властивостей згортання коду. Серед можливих атрибутів:</term>

<listitem>
<para
><userinput
>indentationsensitive</userinput
>: якщо має значення <emphasis
>true</emphasis
>, позначки згортання коду буде додано на основі відступів, так, як це робиться у скриптовій мові Python. Зазвичай, вам не потрібно буде встановлювати цей атрибут, оскільки його типовим значенням є <emphasis
>false</emphasis
>.</para>
</listitem>
</varlistentry>


<varlistentry>
<term
>Елемент <userinput
>indentation</userinput
> у групі <userinput
>general</userinput
> призначено для зазначення інструменту визначення відступів. Ми наполегливо рекомендуємо вам уникати використання цього елемента, оскільки інструмент визначення відступів, зазвичай, визначається або за типом файла або за рядком режиму, доданим до текстового файла. Якщо ви все ж визначите цей інструмент програма примусово буде використовувати саме його, що може бути дуже небажаним для користувача програми. Серед можливих атрибутів:</term>

<listitem>
<para
><userinput
>mode</userinput
>: назва інструменту визначення відступів. У поточній версії можливими значеннями є: <emphasis
>normal, cstyle, haskell, lilypond, lisp, python, ruby</emphasis
> та <emphasis
>xml</emphasis
>.</para>
</listitem>
</varlistentry>


</variablelist>


</sect3>

<sect3 id="kate-highlight-default-styles">
<title
>Можливі типові стилі</title>
<para
>Ви <link linkend="kate-highlight-system-default-styles"
>вже обговорювали</link
> типові стилі у короткому резюме: типовими стилями є наперед визначені набори з гарнітур шрифтів та кольорів.</para>
<variablelist>
<varlistentry>
<term
>Загальні типові стилі:</term>
<listitem>
<para
><userinput
>dsNormal</userinput
>, якщо непотрібне спеціальне підсвічування.</para>
<para
><userinput
>dsKeyword</userinput
>, вбудовані ключові слова мови.</para>
<para
><userinput
>dsFunction</userinput
>, виклики і визначення функцій.</para>
<para
><userinput
>dsVariable</userinput
>, якщо застосовне: назви змінних (наприклад $someVar у PHP/Perl).</para>
<para
><userinput
>dsControlFlow</userinput
>, ключові слова керування обробкою, зокрема if, else, switch, break, return, yield, ...</para>
<para
><userinput
>dsOperator</userinput
>, оператори, зокрема + - * / :: &lt; &gt;</para>
<para
><userinput
>dsBuiltIn</userinput
>, вбудовані функції, класи і об’єкти.</para>
<para
><userinput
>dsExtension</userinput
>, загальні розширення, зокрема класи Qt та функції і макроси у C++ та Python.</para>
<para
><userinput
>dsPreprocessor</userinput
>, інструкції препроцесора або визначення макросів.</para>
<para
><userinput
>dsAttribute</userinput
>, анотації, зокрема @override та __declspec(...).</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>Типові стилі, пов’язані із рядками:</term>
<listitem>
<para
><userinput
>dsChar</userinput
>, окремі символи, зокрема 'x'.</para>
<para
><userinput
>dsSpecialChar</userinput
>, символи із спеціальним призначенням у рядках, зокрема символи екранування, замінники або оператори формальних виразів.</para>
<para
><userinput
>dsString</userinput
>, рядки, зокрема "hello world".</para>
<para
><userinput
>dsVerbatimString</userinput
>, буквальні або необроблювані рядки, зокрема «raw \backlash» у Perl, CoffeeScript та командних оболонках, а також r'\raw' у Python.</para>
<para
><userinput
>dsSpecialString</userinput
>, SQL, формальні вирази, документація HERE, математичний режим LaTeX ...</para>
<para
><userinput
>dsImport</userinput
>, імпорт, включення або потреба у модулях.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>Пов’язані із числами типові стилі:</term>
<listitem>
<para
><userinput
>dsDataType</userinput
>, вбудовані типи даних, наприклад int, void, u64.</para>
<para
><userinput
>dsDecVal</userinput
>, десяткові значення.</para>
<para
><userinput
>dsBaseN</userinput
>, величини у численні з основою, відмінною від 10.</para>
<para
><userinput
>dsFloat</userinput
>, значення із рухомою крапкою.</para>
<para
><userinput
>dsConstant</userinput
>, вбудовані та визначені користувачем сталі, наприклад PI.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>Типові стилі, пов’язані із коментаріми та документацією:</term>
<listitem>
<para
><userinput
>dsComment</userinput
>, коментарі.</para>
<para
><userinput
>dsDocumentation</userinput
>, /** Коментарі у документації */ або """docstrings""".</para>
<para
><userinput
>dsAnnotation</userinput
>, команди документації, зокрема @param, @brief.</para>
<para
><userinput
>dsCommentVar</userinput
>, назви змінних, використаних у попередніх командах, зокрема «foobar» у @param foobar.</para>
<para
><userinput
>dsRegionMarker</userinput
>, позначки області, зокрема //BEGIN, //END у коментарях.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>Інші типові стилі:</term>
<listitem>
<para
><userinput
>dsInformation</userinput
>, нотатки і підказки, наприклад @note у doxygen.</para>
<para
><userinput
>dsWarning</userinput
>, попередження, наприклад @warning у doxygen.</para>
<para
><userinput
>dsAlert</userinput
>, спеціальні слова, наприклад TODO, FIXME, XXXX.</para>
<para
><userinput
>dsError</userinput
>, підсвічування помилок та синтаксичних неточностей.</para>
<para
><userinput
>dsOthers</userinput
>, якщо інше не є застосовним.</para>
</listitem>
</varlistentry>
</variablelist>

</sect3>

</sect2>

<sect2 id="kate-highlight-rules-detailled">
<title
>Правила визначення способу підсвічування</title>

<para
>Цей розділ присвячено опису правил визначення синтаксису.</para>

<para
>Кожне з правил може відповідати нульовій або більшій кількості символів на початку рядка, у якому шукатиметься відповідник правила. Якщо такий відповідник буде знайдено, знайдені символи визначать стиль або <emphasis
>attribute</emphasis
>, вказані за допомогою правила, правило також може надіслати системі запит на зміну поточного контексту.</para>

<para
>Правило виглядає так:</para>

<programlisting
>&lt;НазваПравила attribute=&quot;(ідентифікатор)&quot; context=&quot;(ідентифікатор)&quot; [специфічні для правила атрибути] /&gt;</programlisting>

<para
>Значення <emphasis
>attribute</emphasis
> визначає назву стилю, який буде використано для відповідних символів, а значення <emphasis
>context</emphasis
> визначає контекст, який слід використовувати, починаючи з цього місця.</para>

<para
><emphasis
>context</emphasis
> може бути визначено за допомогою:</para>

<itemizedlist>
<listitem>
<para
><emphasis
>Ідентифікатора</emphasis
>, який є назвою іншого контексту.</para>
</listitem>
<listitem>
<para
>Значення <emphasis
>порядку</emphasis
>, яке повідомляє рушієві, чи слід залишатися у поточному контексті (<userinput
>#stay</userinput
>), чи слід повернутися до попереднього контексту, використаного у рядку (<userinput
>#pop</userinput
>).</para>
<para
>Щоб повернутися на декілька рівнів контексту назад, ключове слово #pop можна повторити декілька разів: <userinput
>#pop#pop#pop</userinput
></para>
</listitem>
<listitem>
<para
>Значення <emphasis
>порядку</emphasis
>, після якого вказано знак оклику (<emphasis
>!</emphasis
>), та значення <emphasis
>ідентифікатора</emphasis
>, яке змусить рушій спочатку використати порядок, а потім перемкнутися на інший контекст, наприклад <userinput
>#pop#pop!OtherContext</userinput
>.</para>
</listitem>
</itemizedlist>

<para
>У деяких правил можуть бути <emphasis
>дочірні правила</emphasis
>, перевірка можливості використання яких виконуватиметься, лише якщо буде задіяно батьківське правило. Атрибути, визначені у батьківському правилі, буде застосовано до всього знайденого рядка. Правило з дочірніми правилами виглядає так:</para>

<programlisting
>&lt;НазваПравила (атрибути)&gt;
  &lt;НазваДочірньогоПравила (атрибути) /&gt;
  ...
&lt;/НазваПравила&gt;
</programlisting>


<para
>Специфічні для правила атрибути можуть бути різними, їх описано у наступних розділах.</para>


<itemizedlist>
<title
>Загальні атрибути</title>
<para
>Всі правила мають перелічені нижче атрибути, їх можна вказувати всюди, де ви побачите напис <userinput
>(загальні атрибути)</userinput
> у списку. Атрибути <emphasis
>attribute</emphasis
> і <emphasis
>context</emphasis
> є обов’язковими атрибутами, всі інші атрибути є необов’язковими. </para>

<listitem>
<para
><emphasis
>attribute</emphasis
>: атрибут, що вказує на визначені <emphasis
>itemData</emphasis
>.</para>
</listitem>
<listitem>
<para
><emphasis
>context</emphasis
>: визначає контекст, на який слід перемкнути систему підсвічування у разі виявлення відповідника правила.</para>
</listitem>
<listitem>
<para
><emphasis
>beginRegion</emphasis
>: почати блок згортання коду. Типове значення: unset.</para>
</listitem>
<listitem>
<para
><emphasis
>endRegion</emphasis
>: закрити блок згортання коду. Типове значення: unset.</para>
</listitem>
<listitem>
<para
><emphasis
>lookAhead</emphasis
>: якщо має значення <emphasis
>true</emphasis
>, система підсвічування не оброблятиме довжину відповідника. Типове значення: <emphasis
>false</emphasis
>.</para>
</listitem>
<listitem>
<para
><emphasis
>firstNonSpace</emphasis
>: відповідність встановлюватиметься, лише якщо рядок є першою відмінною від пробілів послідовністю символів у рядку тексту. Типове значення: <emphasis
>false</emphasis
>.</para>
</listitem>
<listitem>
<para
><emphasis
>column</emphasis
>: збіг буде зареєстровано, якщо збігатиметься рядок. Типове значення: unset.</para>
</listitem>
</itemizedlist>

<itemizedlist>
<title
>Динамічні правила</title>
<para
>Деякі з правил надають змогу встановлювати додатковий атрибут, <userinput
>dynamic</userinput
>, булівського типу з типовим значенням <emphasis
>false</emphasis
>. Якщо атрибут dynamic має значення <emphasis
>true</emphasis
>, у правилі можна використовувати заповнювачі, які позначають текст, знайдений за допомогою правила <emphasis
>формального виразу</emphasis
>, текст буде перемкнуто у поточний контекст у його атрибутах <userinput
>string</userinput
> або <userinput
>char</userinput
>. У атрибуті <userinput
>string</userinput
> заповнювач <replaceable
>%N</replaceable
> (де N — ціле число) буде замінено на відповідний елемент <replaceable
>N</replaceable
> з виклику формального виразу. У атрибуті <userinput
>char</userinput
> заповнювач повинен бути числом <replaceable
>N</replaceable
>, його буде замінено на перший символ відповідного елемента <replaceable
>N</replaceable
> з виклику формального виразу. Всі правила, які дозволяють використання цього атрибута, буде позначено написом <emphasis
>(dynamic)</emphasis
>.</para>

<listitem>
<para
><emphasis
>dynamic</emphasis
>: може мати значення <emphasis
>(true|false)</emphasis
>.</para>
</listitem>
</itemizedlist>

<sect3 id="highlighting-rules-in-detail">
<title
>Докладно про правила</title>

<variablelist>
<varlistentry>
<term
>DetectChar</term>
<listitem>
<para
>Перевірка на рівність одному певному символу. Зазвичай, використовується для пошуку кінця рядків, взятих у лапки.</para>
<programlisting
>&lt;DetectChar char=&quot;(символ)&quot; (загальні атрибути) (dynamic) /&gt;</programlisting>
<para
>Атрибут <userinput
>char</userinput
> визначає символ, з яким відбуватиметься порівняння.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>Detect2Chars</term>
<listitem>
<para
>Перевірка на рівність двом певним символам у вказаному порядку.</para>
<programlisting
>&lt;Detect2Chars char=&quot;(символ)&quot; char1=&quot;(символ)&quot; (загальні атрибути) (dynamic) /&gt;</programlisting>
<para
>Атрибут <userinput
>char</userinput
> визначає перший символ для порівняння, <userinput
>char1</userinput
> — другий.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>AnyChar</term>
<listitem>
<para
>Перевірка на рівність одному з символів вказаного набору.</para>
<programlisting
>&lt;AnyChar String=&quot;(рядок)&quot; (загальні атрибути) /&gt;</programlisting>
<para
>Атрибут <userinput
>String</userinput
> визначає набір символів.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>StringDetect</term>
<listitem>
<para
>Перевірка на рівність вказаному рядку.</para>
<programlisting
>&lt;StringDetect String=&quot;(рядок)&quot; [insensitive=&quot;true|false&quot;] (загальні атрибути) (dynamic) /&gt;</programlisting>
<para
>Атрибут <userinput
>String</userinput
> визначає рядок для порівняння. Типовим значенням атрибута <userinput
>insensitive</userinput
> є <emphasis
>false</emphasis
>, цей атрибут передається функції порівняння рядків. Якщо значенням атрибута буде <emphasis
>true</emphasis
>, порівняння відбуватиметься без врахування регістру.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>WordDetect</term>
<listitem>
<para
>Виявити рядок, але з додатковою вимогою щодо меж слів, зокрема крапки, <userinput
>'.'</userinput
>, або пробілу на початку або у кінці слова. Обробка <userinput
>\b&lt;рядок&gt;\b</userinput
> відбувається подібно до формального виразу, але виконується швидше за обробку правила <userinput
>RegExpr</userinput
>.</para>
<programlisting
>&lt;WordDetect String=&quot;(рядок)&quot; [insensitive=&quot;true|false&quot;] (загальні атрибути) (dynamic) /&gt;</programlisting>
<para
>Атрибут <userinput
>String</userinput
> визначає рядок для порівняння. Типовим значенням атрибута <userinput
>insensitive</userinput
> є <emphasis
>false</emphasis
>, цей атрибут передається функції порівняння рядків. Якщо значенням атрибута буде <emphasis
>true</emphasis
>, порівняння відбуватиметься без врахування регістру.</para>
<para
>Починаючи з Kate 3.5 (KDE 4.5)</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>RegExpr</term>
<listitem>
<para
>Перевірка на збіг з формальним виразом.</para>
<programlisting
>&lt;RegExpr String=&quot;(рядок)&quot; [insensitive=&quot;true|false&quot;] [minimal=&quot;true|false&quot;] (загальні атрибути) (dynamic) /&gt;</programlisting>
<para
>Атрибут <userinput
>String</userinput
> визначає формальний вираз.</para>
<para
>Типовим значенням атрибута <userinput
>insensitive</userinput
> є <emphasis
>false</emphasis
>, цей атрибут передається рушію пошуку за формальним виразом.</para>
<para
>Типовим значенням атрибута <userinput
>minimal</userinput
> є <emphasis
>false</emphasis
>, цей атрибут буде передано рушієві пошуку за формальним виразом.</para>
<para
>Оскільки пошук відповідників для застосування правила завжди відбувається на початку поточного рядка, формальний вираз, що починається з символу каретки (<literal
>^</literal
>) вказує на те, що пошук відповідника правила слід виконувати лише на початку рядка.</para>
<para
>Щоб дізнатися більше, ознайомтеся з розділом <link linkend="regular-expressions"
>Формальні вирази</link
>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>keyword</term>
<listitem>
<para
>Перевірка на рівність ключовому слову з вказаного списку.</para>
<programlisting
>&lt;keyword String=&quot;(назва списку)&quot; (загальні атрибути) /&gt;</programlisting>
<para
>Атрибут <userinput
>String</userinput
> визначає назву списку ключових слів. Список з вказаною назвою має існувати.</para>
<para
>Система підсвічування обробляє правила ключових слів у дуже оптимізований спосіб. Тому абсолютно необхідно, щоб усі ключові слова, які слід знайти, було обмежено визначеними роздільниками, заздалегідь передбаченими (типовими роздільниками) або явно визначеними у властивості <emphasis
>additionalDeliminator</emphasis
> теґу <emphasis
>keywords</emphasis
>.</para>
<para
>Якщо ключове слово, яке слід знайти, має містити символ роздільника, відповідний символ слід додати до властивості <emphasis
>weakDeliminator</emphasis
> теґу <emphasis
>keywords</emphasis
>. Після цього символ втратить властивість роздільності у всіх правилах <emphasis
>keyword</emphasis
>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>Int</term>
<listitem>
<para
>Перевірка на рівність цілому числу.</para>
<para
><programlisting
>&lt;Int (загальні атрибути) (dynamic) /&gt;</programlisting
></para>
<para
>У цього правила немає специфічних атрибутів. Зазвичай, для виявлення символів, що стоять після числа і позначають тип цілого числа у коді програми, <userinput
>L</userinput
> і <userinput
>U</userinput
>, використовуються дочірні правила. Насправді, можна використовувати будь-які правила як дочірні, але у <acronym
>DTD</acronym
> передбачено використання лише правила <userinput
>StringDetect</userinput
>.</para>
<para
>Приклад пошуку цілих чисел, які слідують за символом «L». <programlisting
>&lt;Int attribute="Decimal" context="#stay" &gt;
  &lt;StringDetect attribute="Decimal" context="#stay" String="L" insensitive="true"/&gt;
&lt;/Int&gt;
</programlisting
></para>

</listitem>
</varlistentry>

<varlistentry>
<term
>Float</term>
<listitem>
<para
>Перевірка на рівність числу з плаваючою крапкою.</para>
<para
><programlisting
>&lt;Float (загальні атрибути) /&gt;</programlisting
></para>
<para
>У цього правила немає специфічних атрибутів. Можна використовувати правило <userinput
>AnyChar</userinput
> як дочірнє, це правило типово використовується для виявлення комбінацій, порівняйте з правилом <userinput
>Int</userinput
>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>HlCOct</term>
<listitem>
<para
>Перевірка на відповідність рядка запису вісімкового числа (починається з «0»).</para>
<para
><programlisting
>&lt;HlCOct (загальні атрибути) /&gt;</programlisting
></para>
<para
>У цього правила немає особливих атрибутів.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>HlCHex</term>
<listitem>
<para
>Перевірка на відповідність рядка запису шістнадцяткового числа (починається з «0x»).</para>
<para
><programlisting
>&lt;HlCHex (загальні атрибути) /&gt;</programlisting
></para>
<para
>У цього правила немає особливих атрибутів.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>HlCStringChar</term>
<listitem>
<para
>Перевірка на відповідність символу керівної послідовності.</para>
<para
><programlisting
>&lt;HlCStringChar (загальні атрибути) /&gt;</programlisting
></para>
<para
>У цього правила немає особливих атрибутів.</para>

<para
>Перевірка на відповідність символам, які часто використовуються у коді програм, наприклад <userinput
>\n</userinput
> (перехід на новий рядок) або <userinput
>\t</userinput
> (табуляція).</para>

<para
>Пошук буде виконуватися за переліченими далі символами, якщо ці символи стоять одразу за зворотною навскісною рискою (<literal
>\</literal
>): <userinput
>abefnrtv&quot;'?\</userinput
>. Крім того, відповідними вважатимуться шістнадцяткові числа, наприклад <userinput
>\xff</userinput
>, і екрановані вісімкові числа, наприклад <userinput
>\033</userinput
>.</para>

</listitem>
</varlistentry>

<varlistentry>
<term
>HlCChar</term>
<listitem>
<para
>Перевірка на відповідність символу C.</para>
<para
><programlisting
>&lt;HlCChar (загальні атрибути) /&gt;</programlisting
></para>
<para
>У цього правила немає особливих атрибутів.</para>

<para
>Перевірка на відповідність символам C, взятим у одинарні лапки (Приклад: <userinput
>'c'</userinput
>). Отже, у таких лапках може бути простий символ або екранований символ. Щоб дізнатися про пошук екранованих послідовностей символів, перегляньте пункт для HlCStringChar.</para>

</listitem>
</varlistentry>

<varlistentry>
<term
>RangeDetect</term>
<listitem>
<para
>Перевірка на відповідність рядку з вказаними початковим і кінцевим символами.</para>
<programlisting
>&lt;RangeDetect char=&quot;(символ)&quot;  char1=&quot;(символ)&quot; (загальні атрибути) /&gt;</programlisting>
<para
><userinput
>char</userinput
> визначає символ, який повинен починати діапазон символів, <userinput
>char1</userinput
> — символ, який має завершувати діапазон.</para>
<para
>Корисно для виявлення, наприклад, невеличких рядків у лапках, але зауважте, що, оскільки рушій підсвічування обробляє за раз лише один рядок, у такий спосіб неможливо знайти рядки у лапках, які розбито між декількома рядками документа.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>LineContinue</term>
<listitem>
<para
>Перевірка на відповідність вказаному символу наприкінці рядка.</para>
<programlisting
>&lt;LineContinue (загальні атрибути) [char="\"] /&gt;</programlisting>
<para
>Необов’язковий для встановлення відповідності атрибут <userinput
>char</userinput
>, типовим значенням є символ зворотної риски (<userinput
>'\'</userinput
>). Введено з &kde; 4.13.</para>
<para
>Це правило корисне для перемикання контексту наприкінці рядка. Це потрібно, зокрема, у коді мовами C/C++ для продовження макросів або рядків.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
>IncludeRules</term>
<listitem>
<para
>Включити правила з іншого контексту або мови/файла.</para>
<programlisting
>&lt;IncludeRules context=&quot;посилання на контекст&quot; [includeAttrib=&quot;true|false&quot;] /&gt;</programlisting>

<para
>Атрибут <userinput
>context</userinput
> визначає контекст, який слід включити.</para>
<para
>Якщо значенням є простий рядок, у поточний контекст буде включено всі визначені правила, наприклад: <programlisting
>&lt;IncludeRules context=&quot;anotherContext&quot; /&gt;</programlisting
></para>

<para
>Якщо у рядку міститься послідовність символів <userinput
>##</userinput
>, система підсвічування шукатиме контекст у іншому визначенні мови з вказаною назвою. Приклад: <programlisting
>&lt;IncludeRules context=&quot;String##C++&quot; /&gt;</programlisting
> включить контекст <emphasis
>String</emphasis
> з визначення правил підсвічування для <emphasis
>C++</emphasis
>.</para>
<para
>Якщо атрибут <userinput
>includeAttrib</userinput
> матиме значення <emphasis
>true</emphasis
>, атрибут призначення буде змінено на атрибут джерела. Це потрібно для того, щоб, наприклад, виконати коментування, якщо текст, що відповідає знайденому контексту, має інше підсвічування, ніж текст у основному контексті. </para>
</listitem>
</varlistentry>


<varlistentry>
<term
>DetectSpaces</term>
<listitem>
<para
>Пошук пробілів.</para>
<programlisting
>&lt;DetectSpaces (загальні атрибути) /&gt;</programlisting>

<para
>У цього правила немає особливих атрибутів.</para>
<para
>Цим правилом можна скористатися, якщо вам точно відомо, що перед текстом рядка має бути декілька пробілів, наприклад, на початку рядків з відступом. За допомогою цього правила можна пропустити одразу всі пробіли, замість послідовної перевірки на основі декількох правил, кожне з яких надаватиме змогу відкидати по одному пробілу за один прийом через невідповідність.</para>
</listitem>
</varlistentry>


<varlistentry>
<term
>DetectIdentifier</term>
<listitem>
<para
>Пошук рядків ідентифікаторів (зокрема формальних виразів: [a-zA-Z_][a-zA-Z0-9_]*).</para>
<programlisting
>&lt;DetectIdentifier (загальні атрибути) /&gt;</programlisting>

<para
>У цього правила немає особливих атрибутів.</para>
<para
>Це правило слід використовувати для пропуску рядка з символів, які складають слова, замість послідовної перевірки на основі декількох правил, кожне з яких надаватиме змогу відкидати по одному символу за один прийом через невідповідність.</para>
</listitem>
</varlistentry>

</variablelist>
</sect3>

<sect3>
<title
>Підказки та поради</title>

<itemizedlist>
<para
>Після того, як ви зрозумієте роботу інструменту перемикання контексту, ви зможете писати власні визначення підсвічування. Але вам завжди слід з обережністю ставитися до вибору правил. Формальні вирази є дуже потужним, але досить повільним у порівнянні з іншими, інструментом. Отже, скористайтесь наведеними нижче підказками. </para>

<listitem>
<para
>Якщо вам потрібно перевірити відповідність лише двом символам, скористайтеся правилом <userinput
>Detect2Chars</userinput
>, замість правила <userinput
>StringDetect</userinput
>. Те саме стосується правила <userinput
>DetectChar</userinput
>.</para>
</listitem>
<listitem>
<para
>Формальними виразами просто користуватися, але часто існує інший, набагато швидший спосіб досягти результату. Припустімо вам потрібно перевірити, чи є символ <userinput
>'#'</userinput
> першим символом рядка. Вирішення на основі формального виразу має виглядати десь так: <programlisting
>&lt;RegExpr attribute=&quot;Macro&quot; context=&quot;macro&quot; String=&quot;^\s*#&quot; /&gt;</programlisting
> Того самого результату можна досягти набагато швидше за допомогою такого правила: <programlisting
>&lt;DetectChar attribute=&quot;Macro&quot; context=&quot;macro&quot; char=&quot;#&quot; firstNonSpace=&quot;true&quot; /&gt;</programlisting
> Якщо вам потрібно знайти формальний вираз <userinput
>'^#'</userinput
> ви знову ж таки можете скористатися правилом <userinput
>DetectChar</userinput
> з атрибутом <userinput
>column=&quot;0&quot;</userinput
>. Відлік значення атрибута <userinput
>column</userinput
> засновано на кількості символів, отже табуляція вважатиметься лише одним символом. </para>
</listitem>
<listitem>
<para
>Ви можете перемикати контексти без обробки символів тексту. Припустімо, що вам потрібно перемкнути контекст у разі виявлення рядка <userinput
>*/</userinput
>, але також слід обробити цей рядок у наступному контексті. Ви можете скористатися наведеним нижче правилом, у якому атрибут <userinput
>lookAhead</userinput
> призведе до того, що інструмент визначення підсвічування збереже знайдений рядок для обробки у наступному контексті. <programlisting
>&lt;Detect2Chars attribute=&quot;Comment&quot; context=&quot;#pop&quot; char=&quot;*&quot; char1=&quot;/&quot; lookAhead=&quot;true&quot; /&gt;</programlisting>
</para>
</listitem>
<listitem>
<para
>Скористайтеся <userinput
>DetectSpaces</userinput
>, якщо вам відома точна кількість пробілів.</para>
</listitem>
<listitem>
<para
>Скористайтеся <userinput
>DetectIdentifier</userinput
> замість формального виразу <userinput
>'[a-zA-Z_]\w*'</userinput
>.</para>
</listitem>
<listitem>
<para
>За можливості, використовуйте типові стилі. Таким чином, ви полегшите користувачеві призвичаювання до середовища.</para>
</listitem>
<listitem>
<para
>Зазирайте до інших файлів XML, щоб дізнатися як інші люди реалізують складні правила.</para>
</listitem>
<listitem>
<para
>Ви можете перевірити коректність будь-якого файла XML за допомогою команди <command
>validatehl.sh language.xsd mySyntax.xml</command
>. Файли <filename
>validatehl.sh</filename
> і <filename
>language.xsd</filename
> зберігаються у <ulink url="https://commits.kde.org/syntax-highlighting?path=data/schema"
>сховищі бібліотеки підсвічування синтаксичних конструкцій</ulink
>. </para>
</listitem>
<listitem>
<para
>Якщо у вашому файлі часто вживаються складні формальні вирази, ви можете скористатися визначенням <emphasis
>ENTITIES</emphasis
>. Приклад:</para>
<programlisting
>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE language SYSTEM "language.dtd"
[
        &lt;!ENTITY myref    "[A-Za-z_:][\w.:_-]*"&gt;
]&gt;
</programlisting>
<para
>Після такого визначення ви зможете використовувати <emphasis
>&amp;myref;</emphasis
> замість формального виразу.</para>
</listitem>
</itemizedlist>
</sect3>

</sect2>

</sect1>


<sect1 id="dev-scripting">
<title
>Створення скриптів мовою JavaScript</title>

<para
>Можливості компонента редактора &kappname; можна дуже просто розширити за допомогою написання скриптів. Для написання скриптів слід використовувати мову ECMAScript (широко відому як JavaScript). У &kappname; передбачено підтримку двох типів скриптів: скрипти встановлення відступів та скрипти командного рядка. </para>

<sect2 id="dev-scripting-indentation">
<title
>Скрипти додавання відступів</title>

<para
>Скрипти встановлення відступів, які також будемо називати інструментами відступів, автоматично встановлюють відступи у тексті під час його введення. Наприклад, після натискання клавіші &Enter; програма зазвичай збільшує відступ у наступному рядку. </para>

<para
>У наступних розділах наведено покрокові настанови щодо створення основи простого інструменту відступів. На першому кроці вам слід створити файл <filename
>*.js</filename
> з назвою, наприклад, <filename
>javascript.js</filename
> у локальній домашній теці <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/script/indentation</filename
>. Тут змінна середовища <envar
>XDG_DATA_HOME</envar
> типово має значення <filename
>~/.local</filename
> або <filename
>~/.local/share</filename
>. </para>
<para
>У &Windows; ці файли зберігаються у <filename
>%USER%\AppData\Local\katepart5\indentation</filename
>. <replaceable
>%USERPROFILE%</replaceable
> зазвичай є скороченням для <filename
>C:\\Users\\<replaceable
>користувач</replaceable
></filename
>.</para>

<sect3 id="dev-scripting-indentation-header">
<title
>Заголовок скрипту додавання відступів</title>
<para
>Заголовок файла <filename
>javascript.js</filename
> подається у межах закоментованого блоку і має таку форму <programlisting>
var katescript = {
    "name": "JavaScript",
    "author": "Example Name &lt;example.name@some.address.org&gt;",
    "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
</programlisting
> Нижче ми зупинимося докладніше на кожному з записів заголовка. <itemizedlist>
<listitem
><para
><literal
>name</literal
> [обов’язковий запис]: це назва інструменту відступів, яку буде показано у меню <menuchoice
><guimenu
>Інструменти</guimenu
><guimenuitem
>Відступ</guimenuitem
></menuchoice
> і діалогових вікнах налаштування. </para
></listitem>
<listitem
><para
><literal
>author</literal
> [необов’язковий запис]: ім’я автора та дані щодо способу встановлення з ним зв’язку. </para
></listitem>
<listitem
><para
><literal
>license</literal
> [необов’язковий запис]: скорочена форма умов ліцензування, зокрема BSD або LGPLv3. </para
></listitem>
<listitem
><para
><literal
>revision</literal
> [обов’язковий запис]: версія скрипту. Внесення змін до коду скрипту має призводити до збільшення його версії. </para
></listitem>
<listitem
><para
><literal
>kate-version</literal
> [обов’язковий запис]: мінімальне значення версії &kappname;, у якій працюватиме скрипт. </para
></listitem>
<listitem
><para
><literal
>required-syntax-style</literal
> [необов’язковий запис]: потрібний вам стиль синтаксису, який відповідає вказаному значенням <literal
>style</literal
> у файлах визначення підсвічування синтаксичних конструкцій. Цей запис є важливим для інструментів відступів, які працюють на основі певних даних щодо підсвічування у документі. Якщо буде вказано стиль синтаксичних конструкцій, інструментом відступів можна буде скористатися, лише якщо буде задіяно відповідний інструмент підсвічування тексту. Таким чином можна запобігти «невизначеній поведінці», спричиненій використанням інструменту відступів без потрібної для його роботи схеми підсвічування. Наприклад, у такий спосіб налаштовано інструмент відступів Ruby у файлах <filename
>ruby.js</filename
> і <filename
>ruby.xml</filename
>. </para
></listitem>
<listitem
><para
><literal
>indent-languages</literal
> [необов’язковий запис]: масив JSON стилів синтаксичних конструкцій, які може обробляти інструмент відступів, наприклад <literal
>["c++", "java"</literal
>. </para
></listitem>
<listitem
><para
><literal
>priority</literal
> [необов’язковий запис]: якщо якомусь файлу з визначеним підсвічуванням синтаксичних конструкцій відповідає декілька інструментів відступів, за допомогою цього запису буде встановлено пріоритет застосування інструменту відступів. </para
></listitem>
</itemizedlist>
</para>

</sect3>

<sect3 id="dev-scripting-indentation-body">
<title
>Код інструменту відступів</title>
<para
>Тепер, озброєні знаннями про формат заголовка, ви можете перейти до вивчення того, як же працює сам скрипт встановлення відступів. Основа подібного скрипту виглядає так: <programlisting>
// вимагаємо бібліотек JS katepart, наприклад range.js, якщо використовується Range
require ("range.js");
  
triggerCharacters = "{}/:;";
function indent(line, indentWidth, ch)
{
    //скрипт буде викликано під час обробки символу нового рядка (ch == '\n') і всіх символів, вказаних у
    // загальній змінній triggerCharacters. Під час використання пункту меню <menuchoice
><guimenu
>Інструменти</guimenu
><guimenuitem
>Вирівняти</guimenuitem
></menuchoice>
    // змінна ch матиме порожнє значення, тобто ch == ''.
    //
    // див. також розділ «Інтерфейс (API) роботи зі скриптами»
    return -2;
}
</programlisting
> У функції <function
>indent()</function
> передбачено три параметри: <itemizedlist
> <listitem
><para
><literal
>line</literal
>: рядок, у якому слід встановити відступ</para
></listitem
> <listitem
><para
><literal
>indentWidth</literal
>: ширина відступу у пробілах</para
></listitem
> <listitem
><para
><literal
>ch</literal
>: символ нового рядка (<literal
>ch == '\n'</literal
>), символ перемикання, вказаний за допомогою <literal
>triggerCharacters</literal
> або порожній рядок, якщо користувачем було обрано пункт меню <menuchoice
><guimenu
>Інструменти</guimenu
> <guimenuitem
>Вирівняти</guimenuitem
></menuchoice
>.</para
></listitem
> </itemizedlist
> Значення, повернуте функцією <function
>indent()</function
>, визначатиме спосіб встановлення відступу у рядку. Якщо буде повернуто ціле число, його обробку буде виконано за такими варіантами: <itemizedlist
> <listitem
><para
>повернуто значення <literal
>-2</literal
>: нічого не робити</para
></listitem
> <listitem
><para
>повернуто значення <literal
>-1</literal
>: зберегти відступ (його буде визначено на основі попереднього непорожнього рядка)</para
></listitem
> <listitem
><para
>повернуто значення <literal
> 0</literal
>: числа &gt;= 0 визначають глибину відступу у пробілах</para
></listitem
> </itemizedlist
> Крім того, може бути повернуто масив з двох елементів: <itemizedlist
> <listitem
><para
><literal
>повернуто [ відступ, вирівнювання ];</literal
></para
></listitem
> </itemizedlist
> Першим елементом такого масиву є глибина відступу, подібна на значення, про яке ми говорили раніше. Інший же елемент є абсолютним значенням, що відповідає стовпчику «вирівнювання». Якщо це значення буде більшим за значення відступу, до відступу після додавання відступу, визначеного першим параметром, буде додано різницю між цими значенням. Якщо ж значення другого параметра буде меншим за відступ, його буде проігноровано. Одночасне використання для встановлення відступів пробілів і символів табуляції часто називають «мішаним режимом». </para>

<para
>Розглянемо такий приклад: для встановлення відступів використовується символ табуляції, а ширину відступу визначено як 4 пробіли. У нашому прикладі, &lt;таб&gt; — це символ табуляції, а «.» — пробіл: <programlisting>
1: &lt;таб&gt;&lt;таб&gt;foobar("привіт",
2: &lt;таб&gt;&lt;таб&gt;......."світе");
</programlisting
> Під час встановлення відступу для рядка 2 функція <function
>indent()</function
> повертає значення [8, 15]. У результаті буде додано два символи табуляції для встановлення відступу до стовпчика 8, а потім буде додано 7 пробілів для вирівнювання за другим параметром, більшим за перший, отже рядок залишатиметься вирівняним під час перегляду файла за будь-якої встановленої ширити відступу табуляції. </para>

<para
>У типовому пакунку KDE для &kappname; передбачено декілька інструментів відступів. Код цих інструментів мовою JavaScript зберігається у каталозі <filename
>$<envar
>XDG_DATA_DIRS</envar
>/katepart5/script/indentation</filename
>.</para>
<para
>У &Windows; ці файли зберігаються у <filename
>%USER%\AppData\Local\katepart5\indentation</filename
>. <replaceable
>%USER%</replaceable
> зазвичай є скороченням для <filename
>C:\\Users\\<replaceable
>користувач</replaceable
></filename
>. </para>

<para
>Під час розробки скрипту встановлення відступів корисним буває перезавантаження скриптів для перевірки коректності поведінки під час встановлення відступів. Замість перезапуску програми достатньо просто перейти до командного рядка і виконати команду <command
>reload-scripts</command
>. </para>

<para
>Якщо вами було створено якийсь корисний скрипт, ви зробити його вашим власним внеском до проекту розробки &kappname;. Будь ласка, повідомте про вашу розробку у <ulink url="mailto:kwrite-devel@kde.org"
>списку листування програми</ulink
>. </para>

</sect3>
</sect2>

<sect2 id="dev-scripting-command-line">
<title
>Скрипти командного рядка</title>

<para
>Оскільки всі користувачі мають різні потреби, у &kappname; передбачено підтримку невеличких допоміжних інструментів для пришвидшення роботи з фрагментами тексту за допомогою <link linkend="advanced-editing-tools-commandline"
>вбудованого командного рядка</link
>. Наприклад, команду <command
>sort</command
> (впорядкувати) реалізовано саме за допомогою такого інструменту або скрипту. У цьому розділі ви знайдете пояснення щодо способу створення файлів <filename
>*.js</filename
>, які допоможуть вам розширити можливості &kappname; додаванням допоміжних скриптів. </para>

<para
>Скрипти командного рядка зберігаються у одній теці зі скриптами встановлення відступів. Отже на першому кроці вам слід створити файл <filename
>*.js</filename
> з назвою <filename
>myutils.js</filename
> у локальній домашній теці <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/script/commands</filename
>. Тут змінна середовища <envar
>XDG_DATA_HOME</envar
> типово має значення <filename
>~/.local</filename
> або <filename
>~/.local/share</filename
>.</para>
<para
>У &Windows; ці файли зберігаються у <filename
>%USER%\AppData\Local\katepart5\commands</filename
>. <replaceable
>%USER%</replaceable
> зазвичай є скороченням для <filename
>C:\\Users\\<replaceable
>користувач</replaceable
></filename
>. </para>

<sect3 id="dev-scripting-command-line-header">
<title
>Заголовок скрипту командного рядка</title>
<para
>Заголовок кожного скрипту командної оболонки має бути вбудовано до JSON на початку скрипту так: <programlisting>
var katescript = {
    "author": "Example Name &lt;example.name@some.address.org&gt;",
    "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
</programlisting
> Тепер про кожен із записів докладніше: <itemizedlist>
<listitem
><para
><literal
>author</literal
> [необов’язковий запис]: ім’я автора та дані щодо способу встановлення з ним зв’язку.</para
></listitem>
<listitem
><para
><literal
>license</literal
> [необов’язковий запис]: скорочена форма умов ліцензування, зокрема BSD або LGPLv2.</para
></listitem>
<listitem
><para
><literal
>revision</literal
> [обов’язковий запис]: версія скрипту. Внесення змін до коду скрипту має призводити до збільшення його версії.</para
></listitem>
<listitem
><para
><literal
>kate-version</literal
> [обов’язковий запис]: мінімальне значення версії &kappname;, у якій працюватиме скрипт.</para
></listitem>
<listitem
><para
><literal
>functions</literal
> [обов’язковий запис]: масив JSON команд скрипту.</para
></listitem>
<listitem
><para
><literal
>actions</literal
> [необов’язковий запис]: масив JSON об’єктів JSON, який визначає пункти дій, які буде показано у меню програми. Докладніший опис наведено у розділі щодо <link linkend="advanced-editing-tools-commandline"
>призначення клавіатурних скорочень</link
>.</para
></listitem>
</itemizedlist>
</para>

<para
>Оскільки значення <literal
>functions</literal
> є масивом JSON, окремий скрипт може містити довільну кількість команд для командного рядка. Доступ до кожної із функцій можна оримати за допомогою <link linkend="advanced-editing-tools-commandline"
>вбудованого командного рядка &kappname;</link
>. </para>
</sect3>

<sect3 id="dev-scripting-command-line-body">
<title
>Код скрипту командного рядка</title>

<para
>Всі оголошені у заголовку функції має бути реалізовано у тілі скрипту. Наприклад, у файлі скрипту з наведеного вище прикладу слід реалізувати дві функції, <command
>sort</command
> і <command
>moveLinesDown</command
>. Всі функції має бути записано відповідно до таких синтаксичних правил: <programlisting
>// вимагаємо бібліотек JS katepart, наприклад range.js, якщо використовується Range
require ("range.js");

function &lt;назва&gt;(параметр1, параметр2, ...)
{
    // ...реалізація, див. також: Інтерфейс (API) роботи зі скриптами
}
</programlisting>
</para>

<para
>Параметри у командному рядку передаються функції як <parameter
>параметр1</parameter
>, <parameter
>параметр2</parameter
> тощо. Щоб надати користувачам можливість ознайомлюватися з документацією щодо команди, просто реалізуйте функцію '<function
>help</function
>' у такий спосіб: <programlisting>
function help(cmd)
{
    if (cmd == "sort") {
        return i18n("Sort the selected text.");
    } else if (cmd == "...") {
        // ...
    }
}
</programlisting
>Після цього виконання команди <command
>help sort</command
> у командному рядку призведе до виклику відповідної функції довідки (help) з параметром <parameter
>cmd</parameter
> встановленим у назву вказаної команди, тобто, у нашому прикладі, <parameter
>cmd == "sort"</parameter
>. У відповідь на команду &kappname; покаже користувачеві визначений вами текст довідки. </para>

<para
>Під час розробки скрипту командного рядка корисним буває перезавантаження скриптів для перевірки коректності поведінки під час встановлення відступів. Замість перезапуску програми достатньо просто перейти до командного рядка і виконати команду <command
>reload-scripts</command
>. </para>

<sect4 id="dev-scripting-command-line-shortcuts">
<title
>Призначення клавіатурних скорочень</title>
<para
>Для створення скриптів, доступ до яких можна буде отримувати з меню програми та за допомогою клавіатурних скорочень, скрипт повинен мати надавати відповідний заголовок. У наведеному вище прикладі, обидві функції <literal
>sort</literal
> та <literal
>moveLinesDown</literal
> показують відповідні пункти меню через таку частину заголовка скрипту: <programlisting>
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"
        }
    ]
};
</programlisting
> Поля для однієї дії є такими: <itemizedlist>
<listitem
><para
><literal
>function</literal
> [обов’язкове поле]: пункт функції, який має бути показано у меню <menuchoice
><guimenu
>Інструменти</guimenu
> <guisubmenu
>Скрипти</guisubmenu
></menuchoice
>.</para
></listitem>
<listitem
><para
><literal
>name</literal
> [необов’язковий запис]: текст пункту, який буде показано у меню скриптів.</para
></listitem>
<listitem
><para
><literal
>icon</literal
> [необов’язковий запис]: піктограма, яку буде показано поряд з текстом пункту меню. Можна використовувати назву будь-якої з піктограм KDE.</para
></listitem>
<listitem
><para
><literal
>category</literal
> [необов’язковий запис]: якщо буде вказано категорію, пункт скрипту буде додано у підменю.</para
></listitem>
<listitem
><para
><literal
>shortcut</literal
> [необов’язковий запис]: клавіатурне скорочення, вказане за допомогою цього значення буде типовим. Приклад: <literal
>Ctrl+Alt+t</literal
>. Докладніше про можливі скорочення можна дізнатися з <ulink url="http://qt-project.org/doc/qt-5/qt.html#Key-enum"
>документації до Qt</ulink
>.</para
></listitem>
<listitem
><para
><literal
>interactive</literal
> [необов’язковий]: якщо для роботи скрипту потрібні дані, введені користувачем, встановіть значення <literal
>true</literal
>.</para
></listitem>
</itemizedlist>
</para>

<para
>Якщо вами було створено якийсь корисний скрипт, ви зробити його вашим власним внеском до проекту розробки &kappname;. Будь ласка, повідомте про вашу розробку у <ulink url="mailto:kwrite-devel@kde.org"
>списку листування програми</ulink
>. </para>

</sect4>
</sect3>
</sect2>

<sect2 id="dev-scripting-api">
<title
>Інтерфейс (API) роботи зі скриптами</title>

<para
>Програмним інтерфейсом роботи зі скриптами, основи якого викладено тут, можна користуватися у будь-яких скриптах, зокрема скриптах роботи з відступами та командному рядку програми. Класи <classname
>Cursor</classname
> і <classname
>Range</classname
> визначаються бібліотечними файлами у <filename
>$<envar
>XDG_DATA_DIRS</envar
>/katepart5/libraries</filename
>. Якщо вам потрібно ними скористатися у певному скрипті для використання якихось із функцій <classname
>Document</classname
> або <classname
>View</classname
>, будь ласка, включіть до скрипту потрібну вам бібліотеку такою командою: <programlisting
>// вимагаємо бібліотек JS katepart, наприклад range.js, якщо використовується Range
require ("range.js");
</programlisting>
</para>

<para
>Щоб розширити стандартний програмний інтерфейс (API) для роботи зі скриптами власними функціями і прототипами просто створіть файл у локальній теці файлів налаштування KDE, <filename
>$<envar
>XDG_DATA_HOME</envar
>/katepart5/libraries</filename
>, і включіть його до вашого скрипту за допомогою такого коду: <programlisting
>require ("vashscript.js");
</programlisting>

</para>

<para
>У &Windows; ці файли зберігаються у <filename
>%USER%\AppData\Local\katepart5\libraries</filename
>. <replaceable
>%USER%</replaceable
> зазвичай є скороченням для <filename
>C:\\Users\\<replaceable
>користувач</replaceable
></filename
>.</para>

<para
>Рекомендованим способом розширення можливостей прототипів, зокрема <classname
>Cursor</classname
> або <classname
>Range</classname
>, <emphasis
>не</emphasis
> є внесення змін до загальних файлів <filename
>*.js</filename
>. Для цього вам краще внести зміи до прототипу  <classname
>Cursor</classname
> у JavaScript після команди включення <filename
>cursor.js</filename
> до вашого скрипту за допомогою <literal
>require</literal
>. </para>

<sect3 id="dev-scripting-api-prototypes">
<title
>Курсори і діапазони</title>

<para
>Оскільки &kappname; є текстовим редактором, весь програмний інтерфейс (API) за можливості засновано на курсорах та діапазонах тексту. Об’єкт Cursor (курсор) є простим кортежем <literal
>(line, column)</literal
> (рядок, стовпчик), що визначає позицію у тексті документа. Об’єкт Range (діапазон) це фрагмент тексту від початкової позиції курсора до кінцевої позиції курсора. Докладніше про програмний інтерфейс (API) ми поговоримо у наступних розділах. </para>

<sect4 id="dev-scripting-api-cursors">
<title
>Прототип Cursor (курсор)</title>

<variablelist
><varlistentry>
<term
><synopsis
>Cursor();
</synopsis
></term>
<listitem
><para
>Конструктор. Повертає об’єкт Cursor (курсор) у позиції <literal
>(0, 0)</literal
>.</para>
<para
>Приклад: <function
>var cursor = new Cursor();</function
> </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Cursor(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Конструктор. Повертає об’єкт Cursor (курсор) у позиції (рядок, стовпчик). </para>
<para
>Приклад: <function
>var cursor = new Cursor(3, 42);</function
> </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Cursor(<parameter
>Cursor <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Конструктор копіювання. Повертає копію курсора <replaceable
>інший</replaceable
>. </para>
<para
>Приклад: <function
>var copy = new Cursor(other);</function
> </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Cursor Cursor.clone();
</synopsis
></term>
<listitem
><para
>Повертає клон курсора.</para>
<para
>Приклад: <function
>var clone = cursor.clone();</function
> </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Cursor.setPosition(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>позиція</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Встановлює курсор у місце вказане параметрами <replaceable
>рядок</replaceable
> і <replaceable
>позиція</replaceable
>.</para>
<para
>Актуальна версія: KDE 4.11 </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Cursor.isValid();
</synopsis
></term>
<listitem
><para
>Перевіряє, чи є курсор коректним. Курсор вважається некоректним, якщо значення його позицій у рядку і/або стовпчику дорівнюють <literal
>-1</literal
>. </para>
<para
>Приклад: <function
>var valid = cursor.isValid();</function
> </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Cursor Cursor.invalid();
</synopsis
></term>
<listitem
><para
>Повертає новий некоректний курсор, розташований у позиції <literal
>(-1, -1)</literal
>. </para>
<para
>Приклад: <function
>var invalidCursor = cursor.invalid();</function
> </para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>int Cursor.compareTo(<parameter
>Cursor <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Порівнює поточний курсор з курсором <replaceable
>інший</replaceable
>. Повертає <itemizedlist>
<listitem
><para
><literal
>-1</literal
>, якщо поточний курсор розташовано перед курсором <replaceable
>інший</replaceable
>,</para
></listitem>
<listitem
><para
><literal
>0</literal
>, якщо курсори у однакових позиціях і</para
></listitem>
<listitem
><para
><literal
>+1</literal
>, якщо поточний курсор розташовано після курсора <replaceable
>інший</replaceable
>.</para
></listitem>
</itemizedlist>
</para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Cursor.equals(<parameter
>Cursor <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо цей курсор і курсор <replaceable
>інший</replaceable
> є однаковими. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String Cursor.toString();
</synopsis
></term>
<listitem
><para
>Повертає об’єкт курсора як рядок у формі <quote
><literal
>Cursor(line, column)</literal
></quote
>. </para
></listitem>
</varlistentry
></variablelist>

</sect4>


<sect4 id="dev-scripting-api-ranges">
<title
>Прототип Range (діапазон)</title>

<variablelist
><varlistentry>
<term
><synopsis
>Range();
</synopsis
></term>
<listitem
><para
>Конструктор. Виклик <literal
>new Range()</literal
> повертає Range (діапазон) у (0, 0) - (0, 0). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Range(<parameter
>Cursor <replaceable
>початок</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>кінець</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Конструктор. Виклик функції <literal
>new Range(<replaceable
>початок</replaceable
>, <replaceable
>кінець</replaceable
>)</literal
> повертає Range (діапазон)(<replaceable
>початок</replaceable
>, <replaceable
>кінець</replaceable
>). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Range(<parameter
>int <replaceable
>початковийРядок</replaceable
></parameter
>, <parameter
>int <replaceable
>початковийСтовпчик</replaceable
></parameter
>, <parameter
>int <replaceable
>кінцевийРядок</replaceable
></parameter
>, <parameter
>int <replaceable
>кінцевийСтовпчик</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Конструктор. Виклик функції <literal
>new Range(<replaceable
>початковийРядок</replaceable
>, <replaceable
>початковийСтовпчик</replaceable
>, <replaceable
>кінцевийРядок</replaceable
>, <replaceable
>кінцевийСтовпчик</replaceable
>)</literal
> повертає Range (діапазон) від позиції (<replaceable
>початковийРядок</replaceable
>, <replaceable
>початковийСтовпчик</replaceable
>) до позиції (<replaceable
>кінцевийРядок</replaceable
>, <replaceable
>кінцевийСтовпчик</replaceable
>). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Range(<parameter
>Range <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Конструктор копіювання. Повертає копію Range <replaceable
>інший</replaceable
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Range Range.clone();
</synopsis
></term>
<listitem
><para
>Повертає клон діапазону. </para>
<para
>Приклад: <function
>var clone = range.clone();</function
> </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.isEmpty();
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо початкова і кінцева позиції курсора є рівними. </para>
<para
>Приклад: <function
>var empty = range.isEmpty();</function
> </para>
<para
>Актуальна версія: KDE 4.11 </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.isValid();
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо початкова і кінцева позиції курсора є коректними. Якщо це не так, повертає <literal
>false</literal
>. </para>
<para
>Приклад: <function
>var valid = range.isValid();</function
> </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Range Range.invalid();
</synopsis
></term>
<listitem
><para
>Повертає Range (діапазон) від (-1, -1) до (-1, -1). </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.contains(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо позиція курсора міститься у діапазоні, у іншому випадку повертає <constant
>false</constant
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.contains(<parameter
>Range <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо поточний діапазон містить діапазон <replaceable
>інший</replaceable
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.containsColumn(<parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо <replaceable
>стовпчик</replaceable
> належить напіввідкритому інтервалу <literal
>[start.column, end.column)</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.containsLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо <replaceable
>рядок</replaceable
> належить до напіввідкритого інтервалу <literal
>[start.line, end.line)</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.overlaps(<parameter
>Range <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо поточний діапазон і діапазон <replaceable
>інший</replaceable
> мають ненульовий перетин. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.overlapsLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо <replaceable
>рядок</replaceable
> належить до інтервалу <literal
>[start.line, end.line]</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.overlapsColumn(<parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо <replaceable
>стовпчик</replaceable
> належить інтервалу <literal
>[start.column, end.column]</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.onSingleLine();
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо діапазон починається і завершується на тому самому рядку, тобто якщо <replaceable
>Range.start.line == Range.end.line</replaceable
>. </para>
<para
>Актуальна версія: KDE 4.9 </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool Range.equals(<parameter
>Range <replaceable
>інший</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо поточний діапазон і діапазон <replaceable
>інший</replaceable
> тотожні. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String Range.toString();
</synopsis
></term>
<listitem
><para
>Повертає діапазон у форматі <quote
><literal
>Range(Cursor(line, column), Cursor(line, column))</literal
></quote
>. </para
></listitem>
</varlistentry
></variablelist>

</sect4>
</sect3>

<sect3 id="dev-scripting-api-global">
<title
>Загальні функції (Global Functions)</title>
<para
>У цьому розділі наведено всі загальні функції.</para>


<sect4 id="dev-scripting-api-includes">
<title
>Читання і включення файлів</title>

<variablelist
><varlistentry>
<term
><synopsis
>String read(<parameter
>String <replaceable
>назва файла</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Виконає пошук файла з назвою <replaceable
>назва файла</replaceable
> у каталозі <literal
>katepart/script/files</literal
> і поверне його вміст як рядок. </para
></listitem>
</varlistentry
></variablelist>

<variablelist
><varlistentry>
<term
><synopsis
>void require(<parameter
>String <replaceable
>назва файла</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Виконає пошук файла з назвою <replaceable
>назва файла</replaceable
> у каталозі <literal
>katepart/script/libraries</literal
> і обробить його код. У <literal
>require</literal
> передбачено вбудований захист від повторного включення одного і того самого файла. </para>
<para
>Актуальна версія: KDE 4.10 </para>
</listitem>
</varlistentry
></variablelist>

</sect4>

<sect4 id="dev-scripting-api-debug">
<title
>Налагоджування (Debugging)</title>

<variablelist
><varlistentry>
<term
><synopsis
>void debug(<parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Виводить <replaceable
>текст</replaceable
> до <literal
>stdout</literal
> у консоль, з якої запущено програму. </para
></listitem>
</varlistentry
></variablelist>

</sect4>

<sect4 id="dev-scripting-api-i18n">
<title
>Переклад (Translation)</title>

<para
>Повноцінна локалізація стане можливою лише за використання декількох функцій, призначених для перекладу рядків у скриптах, а саме <literal
>i18n</literal
>, <literal
>i18nc</literal
>, <literal
>i18np</literal
> і <literal
>i18ncp</literal
>. Робота цих функцій подібна до роботи <ulink url="http://techbase.kde.org/Development/Tutorials/Localization/i18n"
>функцій перекладу рядків у KDE</ulink
>. </para>

<para
>За допомогою функцій перекладу і системи перекладу KDE вбудовані у скрипт рядки повідомлень може бути перекладено мовою інтерфейсу програми. Рядки у скриптах, які є частиною офіційної збірки &kappname; буде автоматично видобуто і подано для перекладу командами перекладачів KDE. Іншими словами, якщо ви є розробником основної гілки &kappname;, ви не маєте перейматися видобуванням повідомлень і їхнім перекладом. Втім, слід зауважити, що переклад працюватиме лише у межах інфраструктури &kde;, тобто переклад нових рядків скриптів, розроблених поза межами &kde;, неможливий. Тому вам варто надіслати вашу роботу до основної гілки розробки &kate;, щоб уможливити належний переклад. </para>

<variablelist
><varlistentry>
<term
><synopsis
>void i18n(<parameter
>String <replaceable
>текст</replaceable
></parameter
>, <replaceable
>параметр1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Перекладає <replaceable
>текст</replaceable
> мовою, використаною у інтерфейсі програми. Параметри <replaceable
>параметр1</replaceable
>, ... є необов’язковими. Вони є замінниками рядків <literal
>%1</literal
>, <literal
>%2</literal
> тощо.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>void i18nc(<parameter
>String <replaceable
>контекст</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>, <replaceable
>параметр1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Перекладає <replaceable
>текст</replaceable
> мовою, використаною у інтерфейсі програми. Крім того, перекладачі зможуть побачити рядок <replaceable
>контекст</replaceable
>. За допомогою контексту перекладачам буде простіше правильно перекласти рядок. Параметри <replaceable
>параметр1</replaceable
>, ... є необов’язковими. Вони є замінниками рядків <literal
>%1</literal
>, <literal
>%2</literal
> тощо.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>void i18np(<parameter
>String <replaceable
>однина</replaceable
></parameter
>, <parameter
>String <replaceable
>множина</replaceable
></parameter
>, <parameter
>int <replaceable
>кількість</replaceable
></parameter
>, <replaceable
>параметр1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Перекладає <replaceable
>однину</replaceable
> або <replaceable
>множину</replaceable
> повідомлення мовою, використаною у інтерфейсі програми залежно від вказаного значення <replaceable
>кількість</replaceable
>. Параметри <replaceable
>параметр1</replaceable
>, ... є необов’язковими. Вони є замінниками рядків <literal
>%1</literal
>, <literal
>%2</literal
> тощо.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>void i18ncp(<parameter
>String <replaceable
>контекст</replaceable
></parameter
>, <parameter
>String <replaceable
>однина</replaceable
></parameter
>, <parameter
>String <replaceable
>множина</replaceable
></parameter
>, <parameter
>int <replaceable
>кількість</replaceable
></parameter
>, <replaceable
>параметр1</replaceable
>, ...);
</synopsis
></term>
<listitem
><para
>Перекладає <replaceable
>однину</replaceable
> або <replaceable
>множину</replaceable
> повідомлення мовою, використаною у інтерфейсі програми залежно від вказаного значення <replaceable
>кількість</replaceable
>. Крім того, перекладачі зможуть побачити рядок <replaceable
>контекст</replaceable
>. За допомогою контексту перекладачам буде простіше правильно перекласти рядок. Параметри <replaceable
>параметр1</replaceable
>, ... є необов’язковими. Вони є замінниками рядків <literal
>%1</literal
>, <literal
>%2</literal
> тощо.</para
></listitem>
</varlistentry
></variablelist>

</sect4>
</sect3>

<sect3 id="dev-scripting-api-view">
<title
>Програмний інтерфейс <classname
>View</classname
></title>
<para
>Яким би чином не було запущено скрипт, він завжди користуватиметься загальною змінною <quote
><literal
>view</literal
></quote
>, що відповідає поточній активній панелі перегляду. Нижче наведено список всіх типових функцій об’єкта View. <variablelist
><varlistentry>
<term
><synopsis
><function
>Cursor view.cursorPosition()</function
>
</synopsis
></term>
<listitem
><para
>Повертає поточну позицію курсора у області перегляду.</para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void view.setCursorPosition(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
void view.setCursorPosition(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Встановлює для поточного курсора позицію, вказану напряму (рядок, стовпчик), або позицію вказаного курсора. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Cursor view.virtualCursorPosition();
</synopsis
></term>
<listitem
><para
>Повертає позицію віртуального курсора. Всі символи табуляцій буде враховано за допомогою відповідної кількості пробілів, яка залежатиме від поточної ширини табуляції. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void view.setVirtualCursorPosition(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
void view.setVirtualCursorPosition(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Встановлює для віртуального курсора позицію, вказану напряму (рядок, стовпчик), або позицію вказаного курсора. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String view.selectedText();
</synopsis
></term>
<listitem
><para
>Повертає позначений фрагмент тексту. Якщо жодного фрагменту не позначено, повертає порожній рядок. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool view.hasSelection();
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо у області перегляду позначено фрагмент тексту, інакше повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Range view.selection();
</synopsis
></term>
<listitem
><para
>Повертає діапазон позначеного фрагменту тексту. Якщо жодного фрагменту не позначено, буде повернуто некоректний діапазон. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void view.setSelection(<parameter
>Range <replaceable
>діапазон</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Встановлює позначення тексту за вказаним діапазоном. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void view.removeSelectedText();
</synopsis
></term>
<listitem
><para
>Вилучає позначений текст. Якщо у області перегляду не було позначено жодного тексту, ніяких дій виконано не буде. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void view.selectAll();
</synopsis
></term>
<listitem
><para
>Позначає весь текст у документі. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void view.clearSelection();
</synopsis
></term>
<listitem
><para
>Знімає позначення фрагменту тексту, не вилучаючи сам текст. </para
></listitem>
</varlistentry
></variablelist>
</para>
</sect3>

<sect3 id="dev-scripting-api-document">
<title
>Програмний інтерфейс (API) <classname
>Document</classname
></title>
<para
>Яким би чином не було запущено скрипт, він завжди користуватиметься загальною змінною <quote
><literal
>document</literal
></quote
>, що відповідає поточній активній панелі перегляду. Нижче наведено список всіх типових функцій об’єкта Document. <variablelist
><varlistentry>
<term
><synopsis
>String document.fileName();
</synopsis
></term>
<listitem
><para
>Повертає назву файла документа або порожній рядок для незбережених буферів з текстом. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.url();
</synopsis
></term>
<listitem
><para
>Повертає адресу URL документа повністю або порожній рядок для незбережених буферів з текстом. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.mimeType();
</synopsis
></term>
<listitem
><para
>Повертає тип MIME документа або тип MIME <literal
>application/octet-stream</literal
>, якщо відповідного типу MIME встановити не вдасться. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.encoding();
</synopsis
></term>
<listitem
><para
>Повертає поточне кодування символів, яке буде використано для збереження даних файла. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>String document.highlightingMode();
</synopsis
></term>
<listitem
><para
>Повертає загальний режим підсвічування, використаний у всьому документі. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>String document.highlightingModeAt(<parameter
>Cursor <replaceable
>позиція</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає режим підсвічування, використаний за вказаною позицією у тексті. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>Array document.embeddedHighlightingModes();
</synopsis
></term>
<listitem
><para
>Повертає масив режимів підсвічування, вбудованих до поточного документа. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><synopsis
>bool document.isModified();
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо у документі є незбережені зміни, інакше повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.text();
</synopsis
></term>
<listitem
><para
>Повертає увесь вміст документа у формі єдиного рядка тексту. Розриви рядків буде позначено символом розриву рядка <quote
><literal
>\n</literal
></quote
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.text(<parameter
>int <replaceable
>зРядка</replaceable
></parameter
>, <parameter
>int <replaceable
>зіСтовпчика</replaceable
></parameter
>, <parameter
>int <replaceable
>доРядка</replaceable
></parameter
>, <parameter
>int <replaceable
>доСтовпчика</replaceable
></parameter
>);
String document.text(<parameter
>Cursor <replaceable
>з</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>до</replaceable
></parameter
>);
String document.text(<parameter
>Range <replaceable
>діапазон</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає фрагмент тексту у вказаному діапазоні. Для того, щоб код було легше читати, ми рекомендуємо вам використовувати засновану на об’єктах Cursor і Range версію функції. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.line(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає рядок за його номером у тексті. Якщо вказаний номер не належатиме до діапазону номерів рядків документа, буде повернуто порожній рядок. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.wordAt(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
String document.wordAt(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає слово за вказаною позицією курсора. </para
></listitem>
</varlistentry>


<varlistentry>
<term>
<synopsis
>Range document.wordRangeAt(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
Range document.wordRangeAt(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis>
</term>
<listitem
><para
>Повертає діапазон слова за вказаним розташуванням курсора. Повернуте значення діапазону буде некоректним (див. Range.isValid()), якщо текст розташовано за кінцем рядка. Якщо за вказаним розташуванням курсора не буде слова, функцією буде повернуто порожній діапазон. </para>
<para
>Актуальна версія: KDE 4.9 </para>
</listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.charAt(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
String document.charAt(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає символ за вказаною позицією курсора. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.firstChar(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає перший символ вказаного рядка <replaceable
>рядок</replaceable
>, який не є пробілом. Першим символом рядка вважається символ у стовпчику 0. Якщо рядок є порожнім або складається лише з пробілів, функція повертає порожній рядок. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.lastChar(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає останній символ вказаного рядка <replaceable
>рядок</replaceable
>, який не є пробілом. Якщо рядок є порожнім або складається лише з пробілів, функція повертає порожній рядок. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isSpace(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.isSpace(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо символ у вказаній позиції курсора є пробілом. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.matchesAt(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>);
bool document.matchesAt(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо вказаний <replaceable
>текст</replaceable
> розташовано за відповідною позицією курсора. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.startsWith(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>, <parameter
>bool <replaceable
>пропускатиПробіли</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо рядок з вказаним номером починається з фрагмента тексту <replaceable
>текст</replaceable
>. Якщо це не так, повертає <literal
>false</literal
>. За допомогою параметра <replaceable
>пропускатиПробіли</replaceable
> можна вказати програмі, чи слід ігнорувати пробіли. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.endsWith(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>, <parameter
>bool <replaceable
>пропускатиПробіли</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо рядок з вказаним номером завершується фрагментом тексту <replaceable
>текст</replaceable
>. Якщо це не так, повертає <literal
>false</literal
>. За допомогою параметра <replaceable
>пропускатиПробіли</replaceable
> можна вказати програмі, чи слід ігнорувати пробіли. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.setText(<parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Замінює весь вміст документа на <parameter
>текст</parameter
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.clear();
</synopsis
></term>
<listitem
><para
>Вилучає з документа весь текст. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.truncate(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.truncate(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Обрізає рядок з вказаним номером на вказаному стовпчику або позиції курсора. Повертає <literal
>true</literal
> у разі успіху або <literal
>false</literal
>, якщо рядка з вказаним номером у документі немає. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.insertText(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>);
bool document.insertText(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Вставляє фрагмент тексту <replaceable
>текст</replaceable
> у вказану позицію курсора. Повертає <literal
>true</literal
> у разі успіху або <literal
>false</literal
>, якщо документ відкрито у режимі лише для читання. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.removeText(<parameter
>int <replaceable
>зРядка</replaceable
></parameter
>, <parameter
>int <replaceable
>зіСтовпчика</replaceable
></parameter
>, <parameter
>int <replaceable
>доРядка</replaceable
></parameter
>, <parameter
>int <replaceable
>доСтовпчика</replaceable
></parameter
>);
bool document.removeText(<parameter
>Cursor <replaceable
>з</replaceable
></parameter
>, <parameter
>Cursor <replaceable
>до</replaceable
></parameter
>);
bool document.removeText(<parameter
>Range <replaceable
>діапазон</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Вилучає текст у вказаному діапазоні. Повертає <literal
>true</literal
> у разі успіху або <literal
>false</literal
>, якщо документ відкрито у режимі лише для читання. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.insertLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Вставляє вказаний фрагмент тексту до рядка з вказаним номером. Повертає <literal
>true</literal
> у разі успіху або <literal
>false</literal
>, якщо документ відкрито у режимі лише для читання або рядка з вказаним номером у документі немає. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.removeLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Вилучає рядок з вказаним номером. Повертає <literal
>true</literal
> у разі успіху або <literal
>false</literal
>, якщо документ відкрито у режимі лише для читання або рядка з вказаним номером у документі немає. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.wrapLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.wrapLine(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Обрізає рядок з вказаним номером за вказаним розташуванням курсора. Повертає <literal
>true</literal
> у разі успіху. У інших випадках повертає <literal
>false</literal
> (наприклад, якщо номер рядка &lt; 0). </para>
<para
>Актуальна версія: KDE 4.9 </para>
</listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void document.joinLines(<parameter
>int <replaceable
>початковийРядок</replaceable
></parameter
>, <parameter
>int <replaceable
>кінцевийРядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Об’єднує рядки у діапазоні від<replaceable
>початковийРядок</replaceable
> до <replaceable
>кінцевийРядок</replaceable
>. Послідовні рядки тексту завжди відокремлюються одинарним пробілом. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.lines();
</synopsis
></term>
<listitem
><para
>Повертає кількість рядків у документі. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isLineModified(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо у рядку <replaceable
>рядок</replaceable
> зараз містяться незбережені дані. </para>
<para
>Актуальна версія: &kde; 5.0 </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isLineSaved(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо <replaceable
>рядок</replaceable
> було змінено, після чого документ було збережено. Інакше кажучи, у рядку вже не міститься незбережених даних. </para>
<para
>Актуальна версія: &kde; 5.0 </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isLineTouched(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо у рядку <replaceable
>рядок</replaceable
> зараз містяться незбережені дані або його вміст було раніше змінено. </para>
<para
>Актуальна версія: &kde; 5.0 </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.findTouchedLine(<parameter
>int <replaceable
>початковийРядок</replaceable
></parameter
>, <parameter
>bool <replaceable
>напрямок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Шукати наступний змінений рядок, починаючи з рядка <replaceable
>початковийРядок</replaceable
>. Пошук виконується у напрямку кінця або початку документа залежно від напрямку пошуку, визначеного параметром <replaceable
>напрям</replaceable
>. </para>
<para
>Актуальна версія: &kde; 5.0 </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.length();
</synopsis
></term>
<listitem
><para
>Повертає кількість символів у документі. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.lineLength(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає довжину рядка з номером <replaceable
>рядок</replaceable
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void document.editBegin();
</synopsis
></term>
<listitem
><para
>Започатковує групу редагування для впорядкування операцій зі скасування або повторення дій. Не забувайте, що викликати <function
>editEnd()</function
> слід саме стільки разів, скільки разів було викликано <function
>editBegin()</function
>. Виклики <function
>editBegin()</function
> використовують вбудований лічильник, отже їх може бути вкладено один у оден. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void document.editEnd();
</synopsis
></term>
<listitem
><para
>Завершує групу редагування. Останній виклик <function
>editEnd()</function
> (тобто відповідник першого виклику <function
>editBegin()</function
>) завершує крок з редагування. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.firstColumn(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає перший відмінний від пробілу стовпчик у вказаному за допомогою параметра номера, <replaceable
>рядок</replaceable
>, рядку. Якщо у рядку будуть лише пробіли, функція поверне значення <literal
>-1</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.lastColumn(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає останній відмінний від пробілу стовпчик у вказаному за допомогою параметра номера, <replaceable
>рядок</replaceable
>, рядку. Якщо у рядку будуть лише пробіли, функція поверне значення <literal
>-1</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.prevNonSpaceColumn(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
int document.prevNonSpaceColumn(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає номер стовпчика з символом, відмінним від пробілу. Пошук буде виконано у напрямку початку документа, починаючи з вказаної позиції курсора. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.nextNonSpaceColumn(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
int document.nextNonSpaceColumn(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає номер стовпчика з символом, відмінним від пробілу. Пошук буде виконано у напрямку кінця документа, починаючи з вказаної позиції курсора. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.prevNonEmptyLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає наступний непорожній рядок, що містить символи, відмінні від пробілів. Пошук відбуватиметься у напрямку початку документа. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.nextNonEmptyLine(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає наступний непорожній рядок, що містить символи, відмінні від пробілів. Пошук відбуватиметься у напрямку кінця документа. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isInWord(<parameter
>String <replaceable
>символ</replaceable
></parameter
>, <parameter
>int <replaceable
>атрибут</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо вказаний <replaceable
>символ</replaceable
> з вказаним параметром <replaceable
>атрибут</replaceable
> може бути частиною слова. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.canBreakAt(<parameter
>String <replaceable
>символ</replaceable
></parameter
>, <parameter
>int <replaceable
>атрибут</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо вказаний <replaceable
>символ</replaceable
> з вказаним параметром <replaceable
>атрибут</replaceable
> може бути використано для розбиття рядка. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.canComment(<parameter
>int <replaceable
>атрибутПочатку</replaceable
></parameter
>, <parameter
>int <replaceable
>атрибутКінця</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо діапазон тексту, початок і кінець якого визначаються на основі вказаних атрибутів, можна закоментувати. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.commentMarker(<parameter
>int <replaceable
>атрибут</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає позначку коментаря для окремого рядка коментарів з вказаним параметром <replaceable
>атрибут</replaceable
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.commentStart(<parameter
>int <replaceable
>атрибут</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає позначку, якою має розпочинатися багаторядковий коментар для вказаного значення параметра <replaceable
>атрибут</replaceable
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.commentEnd(<parameter
>int <replaceable
>атрибут</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає позначку, якою має розпочинатися багаторядковий коментар для вказаного значення параметра <replaceable
>атрибут</replaceable
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Range document.documentRange();
</synopsis
></term>
<listitem
><para
>Повертає діапазон всього документа. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Cursor documentEnd();
</synopsis
></term>
<listitem
><para
>Повертає курсор, розташований у останній позиції останнього рядка у документі. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool isValidTextPosition(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>позиція</replaceable
></parameter
>);
bool isValidTextPosition(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо вказану позицію курсора розташовано у коректній позиції у тексті. Позиція у тексті є коректною, лише якщо її розташовано на початку, у середині або у кінці коректного рядка тексту. Крім того, текстова позиція є некоректною, якщо її розташовано посередині замінника символу Unicode. </para
><para
>Актуальна версія: &kde; 5.0 </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.attribute(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
int document.attribute(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає атрибут за вказаною позицією курсора. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isAttribute(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>, <parameter
>int <replaceable
>атрибут</replaceable
></parameter
>);
bool document.isAttribute(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>, <parameter
>int <replaceable
>атрибут</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо атрибут за вказаною позицією курсора дорівнює значенню параметра <replaceable
>атрибут</replaceable
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.attributeName(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
String document.attributeName(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає назву атрибута придатну до читання. Ця назва відповідає назві <literal
>itemData</literal
> у файлах підсвічування синтаксичних конструкцій. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isAttributeName(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>, <parameter
>String <replaceable
>назва</replaceable
></parameter
>);
bool document.isAttributeName(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>, <parameter
>String <replaceable
>назва</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо назва атрибута у певній позиції курсора відповідає вказаному значенню параметра <replaceable
>назва</replaceable
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>String document.variable(<parameter
>String <replaceable
>ключ</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає значення вказаної змінної документа <replaceable
>ключ</replaceable
>. Якщо змінної з вказаною назвою у документі не існує, повертає порожній рядок. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>void document.setVariable(<parameter
>String <replaceable
>ключ</replaceable
></parameter
>, <parameter
>String <replaceable
>значення</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Встановлює значення відповідної змінної документа <replaceable
>ключ</replaceable
>. </para>
<para
>Див. також <link linkend="config-variables"
>змінні документа Kate</link
> </para>
<para
>Актуальна версія: KDE 4.8 </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.firstVirtualColumn(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає віртуальний стовпчик першого відмінного від пробілу символу у вказаному рядку або <literal
>-1</literal
>, якщо рядок є порожнім або містить лише символи пробілів. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.lastVirtualColumn(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає віртуальний стовпчик останнього відмінного від пробілу символу у вказаному рядку або <literal
>-1</literal
>, якщо рядок є порожнім або містить лише символи пробілів. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.toVirtualColumn(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
int document.toVirtualColumn(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
Cursor document.toVirtualCursor(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Перетворює вказану «реальну» позицію курсора на віртуальну позицію курсора, повертає або ціле значення (int), або об’єкт Cursor. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.fromVirtualColumn(<parameter
>int <replaceable
>line</replaceable
></parameter
>, <parameter
>int <replaceable
>virtualColumn</replaceable
></parameter
>);
int document.fromVirtualColumn(<parameter
>Cursor <replaceable
>virtualCursor</replaceable
></parameter
>);
Cursor document.fromVirtualCursor(<parameter
>Cursor <replaceable
>віртуальнийКурсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Перетворює вказану віртуальну позицію курсора на «реальну» позицію курсора, повертає або ціле значення (int), або об’єкт Cursor. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Cursor document.anchor(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>, <parameter
>Char <replaceable
>символ</replaceable
></parameter
>);
Cursor document.anchor(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>, <parameter
>Char <replaceable
>символ</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Виконує пошук у напрямку початку документа, починаючи від вказаної позиції курсора, вказаного символу. Наприклад, якщо функції буде передано символ «(», функція поверне позицію початкової дужки «(». Відповідність дужок не враховуватиметься, тобто інші «(...)» буде проігноровано. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>Cursor document.rfind(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>, <parameter
>int <replaceable
>атрибут</replaceable
> = -1</parameter
>);
Cursor document.rfind(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>, <parameter
>String <replaceable
>текст</replaceable
></parameter
>, <parameter
>int <replaceable
>атрибут</replaceable
> = -1</parameter
>);
</synopsis
></term>
<listitem
><para
>Виконує пошук у напрямку початку документа вказаного фрагмента тексту з відповідним значенням параметра <replaceable
>атрибут</replaceable
>. Параметр <replaceable
>атрибут</replaceable
> буде проігноровано, якщо він матиме значення <literal
>-1</literal
>. Функція поверне значення некоректного курсора, якщо фрагмент тексту знайти не вдасться. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>int document.defStyleNum(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
int document.defStyleNum(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає типовий стиль курсора, використаний за вказаною позицією у тексті. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isCode(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.isCode(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо атрибут за вказаною позицією курсора не дорівнює жодному зі значень стилів: <literal
>dsComment</literal
>, <literal
>dsString</literal
>, <literal
>dsRegionMarker</literal
>, <literal
>dsChar</literal
>, <literal
>dsOthers</literal
>. </para
></listitem>
</varlistentry>



<varlistentry>
<term
><synopsis
>bool document.isComment(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.isComment(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо значенням атрибута символу у позиції курсора є <literal
>dsComment</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isString(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.isString(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо значенням атрибута символу у позиції курсора є <literal
>dsString</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isRegionMarker(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.isRegionMarker(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо значенням атрибута символу у позиції курсора є <literal
>dsRegionMarker</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isChar(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.isChar(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо значенням атрибута символу у позиції курсора є <literal
>dsChar</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry>


<varlistentry>
<term
><synopsis
>bool document.isOthers(<parameter
>int <replaceable
>рядок</replaceable
></parameter
>, <parameter
>int <replaceable
>стовпчик</replaceable
></parameter
>);
bool document.isOthers(<parameter
>Cursor <replaceable
>курсор</replaceable
></parameter
>);
</synopsis
></term>
<listitem
><para
>Повертає <literal
>true</literal
>, якщо значенням атрибута символу у позиції курсора є <literal
>dsOthers</literal
>. Якщо це не так, повертає <literal
>false</literal
>. </para
></listitem>
</varlistentry
></variablelist>
</para>

</sect3>
</sect2>

</sect1>

</chapter>