<chapter id="advanced-editing-tools">
<chapterinfo>
<authorgroup>
<author
>&Anders.Lund; &Anders.Lund.mail;</author>
<author
>&Dominik.Haumann; &Dominik.Haumann.mail;</author>
<othercredit role="translator"
><firstname
>Юрій</firstname
><surname
>Чорноіван</surname
><affiliation
><address
><email
>yurchor@ukr.net</email
></address
></affiliation
><contrib
>Переклад українською</contrib
></othercredit
> 
</authorgroup>
</chapterinfo>
<title
>Додаткові інструменти редагування</title>

<sect1 id="advanced-editing-tools-comment">

<title
>Додавання/Вилучення позначок коментаря</title>

<para
>За допомогою пунктів «Закоментувати» і «Розкоментувати» меню <guimenu
>Інструменти</guimenu
> ви зможете додавати або вилучати позначки коментарів до позначеного фрагмента або поточного рядка (у разі, якщо нічого не позначено), якщо коментарі підтримуються форматом файла, який ви редагуєте.</para>

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

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

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

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

<para
><indexterm
><primary
>закоментувати</primary
></indexterm
> Щоб додати позначки коментарів, скористайтеся пунктом меню <menuchoice
><guimenu
>Інструменти</guimenu
> <guimenuitem
>Закоментувати</guimenuitem
></menuchoice
> або відповідною комбінацією клавіш, типовою комбінацією є <keycombo action="simul"
>&Ctrl;<keycap
>D</keycap
></keycombo
>.</para>

<para
><indexterm
><primary
>розкоментувати</primary
></indexterm
> Щоб вилучити позначки коментарів, скористайтеся пунктом меню <menuchoice
><guimenu
>Інструменти</guimenu
> <guimenuitem
>Розкоментувати</guimenuitem
></menuchoice
> або відповідною комбінацією клавіш, типовою комбінацією є <keycombo action="simul"
>&Ctrl;&Shift;<keycap
>D</keycap
></keycombo
>.</para>

</sect1>

<sect1 id="advanced-editing-tools-commandline">
<title
>Командний рядок компонента редактора</title>

<para
>У компонент редактора &kappname; вбудовано інструмент для роботи з командним рядком, за допомогою якого ви зможете виконувати різноманітні дії за мінімального графічного інтерфейсу. Командний рядок — це текстова панель у нижній частині вікна редактора, щоб увімкнути показ цієї панелі скористайтеся пунктом меню <menuchoice
><guimenu
>Перегляд</guimenu
> <guimenuitem
>Перемкнутися до командного рядка</guimenuitem
></menuchoice
> або скористайтеся клавіатурним скороченням (типовим клавіатурним скороченням є <keycombo action="simul"
><keycap
>F7</keycap
></keycombo
>). У редакторі передбачено набір команд, документацію з яких наведено нижче, та додаткові команди, за допомогою яких можна керувати додатками до програми.</para>

<para
>Щоб виконати команду, введіть цю команду до командного рядка і натисніть клавішу &Enter;. За командним рядком ви зможете визначити, чи було виконано команду, у ньому ж можна переглянути повідомлення, яке могло бути виведено у відповідь на команду. Якщо ви вводили команду за після натискання клавіші <keycap
>F7</keycap
>, за декілька секунд панель командного рядка буде приховано. Щоб витерти виведене командою повідомлення і ввести нову команду, натисніть клавішу <keycap
>F7</keycap
> ще раз.</para>

<para
>У командний рядок вбудовано довідкову систему. Щоб розпочати роботу з довідкою, введіть команду <command
>help</command
>. Щоб переглянути список можливих команд, введіть команду <command
>help list</command
>. Щоб переглянути довідку з окремої команди, виконайте команду <command
>help <replaceable
>назва_команди</replaceable
></command
>.</para>

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

<sect2 id="advanced-editing-tools-commandline-commands">
<title
>Стандартні команди командного рядка</title>

<variablelist>
<title
>Типи аргументів</title>

<varlistentry>
<term
>BOOLEAN</term>
<listitem
><para
>Цей тип використовується для команд, які вмикають або вимикаю певні налаштування. Можливими значеннями таких параметрів є <userinput
>on</userinput
>, <userinput
>off</userinput
>, <userinput
>true</userinput
>, <userinput
>false</userinput
>, <userinput
>1</userinput
> і <userinput
>0</userinput
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
>INTEGER</term>
<listitem
><para
>Ціле число.</para
></listitem>
</varlistentry>

<varlistentry>
<term
>STRING</term>
<listitem
><para
>Рядок, обмежений одинарними лапками (') або подвійними лапками ("), якщо у ньому містяться пробіли.</para
></listitem>
</varlistentry>

</variablelist>



<sect3 id="advanced-editing-tools-commandline-commands-configure">
<title
>Команди налаштування редактора</title>

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

<variablelist>

<varlistentry>
<term
><cmdsynopsis
><command
>set-tab-width</command
><arg choice="req"
>INTEGER ширина</arg
></cmdsynopsis
></term>
<listitem
><para
>Встановлює ширину табуляції у значення <userinput
>ширина</userinput
>.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-indent-width</command
><arg choice="req"
>INTEGER ширина</arg
></cmdsynopsis
></term>
<listitem
><para
>Встановлює відступ у значення кількості пробілів, визначене параметром <userinput
>ширина</userinput
>. Використовується, лише якщо увімкнено відступи з пробілів.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-word-wrap-column</command
><arg choice="req"
>INTEGER довжина</arg
></cmdsynopsis
></term>
<listitem
><para
>Встановлює для параметра максимальної довжини рядка для примусового перенесення значення <userinput
>довжина</userinput
>. Цей параметр використовується, якщо увімкнено автоматичне розбиття тексту на рядки.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-icon-border</command
><arg choice="req"
>BOOLEAN вмикання</arg
> </cmdsynopsis
></term>
<listitem
><para
>Встановлює видимість бічної смужки піктограм.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-folding-markers</command
><arg choice="req"
>BOOLEAN вмикання</arg
></cmdsynopsis
></term>
<listitem
><para
>Встановлює значення видимості позначок панелі згортання.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-line-numbers</command
><arg choice="req"
>BOOLEAN вмикання</arg
></cmdsynopsis
></term>
<listitem
><para
>Встановлює значення видимості панелі номерів рядків.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-replace-tabs</command
><arg choice="req"
>BOOLEAN вмикання</arg
></cmdsynopsis
></term>
<listitem
><para
>Якщо має значення «true», введені вами знаки табуляції буде замінено пробілами. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-remove-trailing-space</command
><arg choice="req"
>BOOLEAN вмикання</arg
></cmdsynopsis
></term>
<listitem
><para
>Якщо цей параметр буде увімкнено, після переведення курсора на інших рядок пробіли наприкінці поточного рядка вилучатимуться.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-show-tabs</command
><arg choice="req"
>BOOLEAN вмикання</arg
></cmdsynopsis
></term>
<listitem
><para
>Якщо буде увімкнено цей параметр, символи табуляції і пробіли наприкінці рядка буде показано у вигляді маленьких крапок.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-show-indent</command
><arg choice="req"
>BOOLEAN вмикання</arg
></cmdsynopsis
></term>
<listitem
><para
>Якщо буде увімкнено цей параметр, відступи буде показано вертикальною крапчастою лінією.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-indent-spaces</command
><arg choice="req"
>BOOLEAN вмикання</arg
></cmdsynopsis
></term>
<listitem
><para
>Якщо буде увімкнено цей параметр, редактор робитиме відступ на <option
>indent-width</option
> пробілів, замість символу табуляції, під час переходу на наступний рівень відступу.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-mixed-indent</command
><arg choice="req"
>BOOLEAN вмикання</arg
></cmdsynopsis
></term>
<listitem
><para
>Якщо буде увімкнено цей параметр, &kappname; використовуватиме суміш з символів табуляції і пробілів для додавання відступів. Ширина кожного з рівнів відступу визначатиметься значенням параметра <option
>indent-width</option
>, загальний же відступ буде оптимізовано так, щоб у ньому використовувалася максимальна кількість символів табуляції.</para>
<para
>Після виконання цієї команди буде увімкнено створення відступів пробілами, якщо ширину відступу не було вказано, буде встановлено значення ширини відступу у половину значення параметра документа <option
>tab-width</option
> на час виконання команди.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-word-wrap</command
><arg choice="req"
>BOOLEAN вмикання</arg
></cmdsynopsis
></term>
<listitem
><para
>Встановлює значення для динамічного перенесення слів у <userinput
>вмикання</userinput
> (true або false)</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-replace-tabs-save</command
><arg choice="req"
>BOOLEAN вмикання</arg
></cmdsynopsis
></term>
<listitem
><para
>Якщо увімкнути цей параметр, під час збереження документа символи табуляції буде замінено на пробіли.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-remove-trailing-space-save</command
><arg choice="req"
>BOOLEAN вмикання</arg
></cmdsynopsis
></term>
<listitem
><para
>Якщо увімкнути цей параметр, під час збереження документа пробіли наприкінці рядків документа будуть вилучатися.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-indent-mode</command
><arg choice="req"
>STRING назва</arg
></cmdsynopsis
></term>
<listitem
><para
>Встановлює режим автоматичного встановлення відступів у значення <userinput
>назва</userinput
>. Якщо програмі не вдасться розпізнати параметр <userinput
>назва</userinput
>, буде встановлено режим 'none'. Коректними значеннями режиму є «none», «normal», «cstyle», «haskell», «lilypond», «lisp», «python», «ruby» і «xml».</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-auto-ident</command
><arg choice="req"
>BOOLEAN скрипт</arg
></cmdsynopsis
></term>
<listitem
><para
>Увімкнути або вимкнути автоматичне встановлення відступів.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-highlight</command
><arg choice="req"
>STRING підсвічування</arg
></cmdsynopsis
></term>
<listitem
><para
>Визначає систему підсвічування синтаксису для поточного документа. Параметром команди має бути коректна назва підсвічування у тому вигляді, у якому ця система фігурує у меню <menuchoice
><guimenu
>Інструменти</guimenu
> <guisubmenu
>Підсвічування</guisubmenu
></menuchoice
>. У цій команді передбачено автоматичне доповнення параметра за списком.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>reload-scripts</command
></cmdsynopsis
></term>
<listitem
><para
>Перезавантажити всі <link linkend="advanced-editing-tools-scripting"
>скрипти JavaScript</link
>, використані Kate, зокрема скрипти встановлення відступів та скрипти командного рядка.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>set-mode</command
><arg choice="req"
>STRING режим</arg
></cmdsynopsis
></term>
<listitem
><para
>Вибрати схему типів файлів для поточного документа. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>nn[oremap]</command
><arg choice="req"
>STRING початкова</arg
> <arg choice="req"
>STRING відображена</arg
></cmdsynopsis
></term>
<listitem
><para
>Відобразити послідовність символів <userinput
>початкова</userinput
> на послідовність <userinput
>відображена</userinput
>.</para
></listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3 id="advanced-editing-tools-commandline-commands-edit">
<title
>Команди редагування</title>

<para
>Наступні команди змінюють вміст поточного документа.</para>

<variablelist>
<varlistentry>
<term
><cmdsynopsis
><command
>indent</command
></cmdsynopsis
></term>
<listitem
><para
>Додає відступ у позначені рядки або поточний рядок.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>unindent</command
></cmdsynopsis
></term>
<listitem
><para
>Вилучає початковий відступ з позначених рядків або поточного рядка.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>cleanindent</command
></cmdsynopsis
></term>
<listitem
><para
>Вилучає відступи для позначених рядків або поточного рядка відповідно до параметрів відступів поточного документа. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>comment</command
></cmdsynopsis
></term>
<listitem
><para
>Додає позначки коментаря, які роблять позначений фрагмент тексту, позначені рядки або поточний рядок коментарями, відповідно до формату тексту, який визначено у параметрах підсвічування синтаксису поточного документа.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>uncomment</command
></cmdsynopsis
></term>
<listitem
><para
>Вилучає позначки коментаря, які роблять позначений фрагмент тексту, позначені рядки або поточний рядок коментарями, відповідно до формату тексту, який визначено у параметрах підсвічування синтаксису поточного документа.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>kill-line</command
></cmdsynopsis
></term>
<listitem
><para
>Вилучає поточний рядок.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>replace</command
><arg choice="req"
> STRING шаблон</arg
> <arg choice="req"
>STRING замінник</arg
></cmdsynopsis
></term>
<listitem
><para
>Замінює текст, що відповідає <userinput
>шаблону</userinput
>, на текст, вказаний у <userinput
>заміннику</userinput
>. Якщо вам потрібно включити пробіл у <userinput
>шаблон</userinput
>, вам слід взяти як <userinput
>шаблон</userinput
>, так і <userinput
>замінник</userinput
> у одинарні або подвійні лапки. Якщо у команді не буде лапок, перше зі слів-параметрів вважатиметься <userinput
>шаблоном</userinput
>, а решта — <userinput
>замінником</userinput
>. Якщо параметр <userinput
>замінник</userinput
> буде порожнім, всі рядки, які відповідають <userinput
>шаблону</userinput
> буде вилучено з тексту.</para>
<para
>Ви можете вказати прапорці налаштування пошуку за допомогою додавання двокрапки, за якою слід вказати одну або декілька літер, кожна з яких відповідатиме за налаштування. Команда викладатиме так: <userinput
>replace:параметри шаблон замінник</userinput
>. Можливі параметри: <variablelist>

<varlistentry>
<term
><userinput
>b</userinput
></term>
<listitem
><para
>Пошук назад.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>c</userinput
></term>
<listitem
><para
>Шукати від позиції курсора.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>e</userinput
></term>
<listitem
><para
>Шукати лише у позначеному фрагменті.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>r</userinput
></term>
<listitem
><para
>Пошук за формальним виразом. Якщо встановлено цей прапорець, ви зможете використовувати параметр <userinput
>\N</userinput
>, де N — номер підрядка у рядку «замінник».</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>s</userinput
></term>
<listitem
><para
>Виконати пошук з врахуванням регістру.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>p</userinput
></term>
<listitem
><para
>Запитувати про дозвіл на заміну наступного елемента.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>w</userinput
></term>
<listitem
><para
>Шукати лише цілі слова.</para
></listitem>
</varlistentry>

</variablelist>

</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>date</command
><arg choice="req"
>STRING формат</arg
></cmdsynopsis
></term>
<listitem
><para
>Вставляє дату/час у форматі, визначеному параметром <userinput
>формат</userinput
>, або у форматі <quote
>yyyy-MM-dd hh:mm:ss</quote
>, якщо рядок формату не буде вказано. Під час обробки рядка <userinput
>формат</userinput
> буде використано такі перетворення: <informaltable
> <tgroup cols="2"
> <tbody>
<row
><entry
><literal
>d</literal
></entry
><entry
>Номер дня без початкового нуля (1-31).</entry
></row>
<row
><entry
><literal
>dd</literal
></entry
><entry
>Номер дня з початковим нулем (01-31).</entry
></row>
<row
><entry
><literal
>ddd</literal
></entry
><entry
>Скорочена локалізована назва дня тижня (наприклад «пн» або «нд»).</entry
></row>
<row
><entry
><literal
>dddd</literal
></entry
><entry
>Довга локалізована назва дня (наприклад «понеділок» або «неділя»).</entry
></row>
<row
><entry
><literal
>M</literal
></entry
><entry
>Номер місяця без початкового нуля (1-12).</entry
></row>
<row
><entry
><literal
>MM</literal
></entry
><entry
>Номер місяця з початковим нулем (01-12).</entry
></row>
<row
><entry
><literal
>MMMM</literal
></entry
><entry
>Повна локалізована назва місяця (наприклад, «січень» або «грудень»).</entry
></row>
<row
><entry
><literal
>MMM</literal
></entry
><entry
>Скорочена локалізована назва місяця (наприклад «січ» або «гру»).</entry
></row>
<row
><entry
><literal
>yy</literal
></entry
><entry
>Рік як двоцифрове значення (00-99).</entry
></row>
<row
><entry
><literal
>yyyy</literal
></entry
><entry
>Рік як чотирицифрове значення (1752-8000).</entry
></row>
<row
><entry
><literal
>h</literal
></entry
><entry
>Години без початкового нуля (0..23 або 1..12 з показом до опівдня/після опівдня).</entry
></row>
<row
><entry
><literal
>hh</literal
></entry
><entry
>Години з початковим нулем (00..23 або 01..12 з показом до опівдня/після опівдня).</entry
></row>
<row
><entry
><literal
>m</literal
></entry
><entry
>Хвилини без початкового нуля (0..59).</entry
></row>
<row
><entry
><literal
>mm</literal
></entry
><entry
>Хвилини з початковим нулем (00..59).</entry
></row>
<row
><entry
><literal
>s</literal
></entry
><entry
>Секунди без початкового нуля (0..59).</entry
></row>
<row
><entry
><literal
>ss</literal
></entry
><entry
>Секунди з початковим нулем (00..59).</entry
></row>
<row
><entry
><literal
>z</literal
></entry
><entry
>Мілісекунди без початкових нулів (0..999).</entry
></row>
<row
><entry
><literal
>zzz</literal
></entry
><entry
>Мілісекунди з початковими нулями (000..999).</entry
></row>
<row
><entry
><literal
>AP</literal
></entry
><entry
>Використовувати показ у форматі AM/PM (до опівдня/після опівдня). AP буде замінено на рядок «AM» або рядок «PM».</entry
></row>
<row
><entry
><literal
>ap</literal
></entry
><entry
>Використовувати показ у форматі am/pm (до опівдня/після опівдня). ap буде замінено на рядок «am» або рядок «pm».</entry
></row>
</tbody>
</tgroup>
</informaltable>

</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>char</command
><arg choice="req"
>STRING ідентифікатор</arg
></cmdsynopsis
></term>
<listitem>
<para
>За допомогою цієї команди можна вводити символи за їх числовими ідентифікаторами у десятковій, вісімковій або шістнадцятковій формі. Щоб скористатися нею, відкрийте діалогове вікно редагування команди і введіть команду <userinput
>char: [число]</userinput
> у поле для введення, а потім натисніть кнопку <guibutton
>Гаразд</guibutton
>.</para>

<example>
<title
>Приклади команди <command
>char</command
></title>

<para
>Ввід: <userinput
>char:234</userinput
></para>
<para
>Вивід: <computeroutput
>&#234;</computeroutput
></para>
<para
>Ввід: <userinput
>char:0x1234</userinput
></para>
<para
>Вивід: <computeroutput
>&#x1234;</computeroutput
></para>
</example>

</listitem>
</varlistentry>

<varlistentry>
<term>
<indexterm
><primary
>заміна, sed-стиль</primary>
<secondary
>пошук, sed-стиль</secondary
></indexterm>
<command
>s///[ig]</command
> <command
>%s///[ig]</command
></term>

<listitem>
<para
>За допомогою цієї команди можна виконати дію з пошуку або заміни у стилі sed у поточному рядку або у всьому файлі (<command
>%s///</command
>).</para>

<para
>Якщо коротко, у тексті буде виконано пошук за <emphasis
>шаблоном пошуку</emphasis
>, формальним виразом між першою і другою навскісними рисками, якщо буде знайдено відповідний фрагмент тексту, його буде замінено на вираз між середньою і останньою навскісними рисками у рядку. За допомогою круглих дужок можна створювати <emphasis
>зворотні посилання</emphasis
>: команда запам’ятає частину виразу, яка відповідає рядку між дужками і використає рядки, які будуть у пам’яті для шаблону заміни, — посилання на ці рядки можна вказати як <userinput
>\1</userinput
> для першого набору у дужках, <userinput
>\2</userinput
> для другого тощо.</para>

<para
>Щоб знайти символ <literal
>(</literal
> або символ <literal
>)</literal
>, вам слід <emphasis
>екранувати</emphasis
> ці символи за допомогою зворотної навскісної риски: <userinput
>\(\)</userinput
></para>

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

<example>

<title
>Заміна тексту у поточному рядку</title>

<para
>Припустімо, компілятор, яким ви збирали вашу програму, повідомив вам про те, що клас <classname
>myClass</classname
>, який згадується у рядку 3902 коду вашої програми не визначено.</para>

<para
>Ви подумаєте: «Оце тобі, то це ж має бути мій клас <classname
>MyClass</classname
>». Ви переходите до рядка 3902 і, замість спроб знайти потрібне слово у тексті, відкриваєте діалогове вікно редагування команди, вводите у нього <userinput
>s/myclass/MyClass/i</userinput
>, натискаєте кнопку <guibutton
>Гаразд</guibutton
>, зберігаєте файл і компілюєте його ще раз, — все, помилки немає.</para>

</example>

<example>
<title
>Заміна тексту у всьому файлі</title>

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

<para
>Відкрийте вікно командного рядка і введіть туди команду <userinput
>%s/пані Іванченко/пані Петренко/</userinput
>, а потім натисніть клавішу &Enter;, — решту зробить програма.</para>

</example>

<example>
<title
>Складніший приклад</title>

<para
>У цьому прикладі ми познайомилися з використанням <emphasis
>зворотніх посилань</emphasis
>, а також <emphasis
>класу символів</emphasis
> (якщо вам не знайомі ці терміни, будь ласка, зверніться до відповідної документації, посилання на яку ви зможете знайти далі за текстом).</para>

<para
>Припустімо, що у вас є такий рядок: <programlisting
>void MyClass::DoStringOps( String      &amp;foo, String &amp;bar, String *p, int  &amp;a, int &amp;b )</programlisting>
</para>
<para
>Тепер вам здається, що цей код виглядає кострубато: ви вирішили скористатися ключовим словом <constant
>const</constant
> для всіх параметрів <quote
>address of</quote
>, у яких назві аргументу передує оператор &amp;. Ви також бажаєте вилучити зайві пробіли так, щоб між будь-якими двома словами був лише один символ пробілу.</para>

<para
>Відкрийте діалогове вікно редагування команди і введіть таку команду: <userinput
>s/\s+(\w+)\s+(&amp;)/ const \1 \2/g</userinput
>. Натисніть кнопку <guibutton
>Гаразд</guibutton
>. Літера <userinput
>g</userinput
> наприкінці виразу наказує програмі перебудовувати формальний вираз для кожного зі знайдених елементів, щоб зберегти  <emphasis
>зворотні посилання</emphasis
>.</para>

<para
>Вивід: <computeroutput
>void MyClass::DoStringOps( const String &amp;foo, const String &amp;bar String *p, const int &amp;a, const int &amp;b )</computeroutput
></para>

<para
>Справу зроблено! Що ж сталося? Гаразд, було виконано пошук інтервалу з пробілів (<literal
>\s+</literal
>), за яким слідує один або декілька символів абетки (<literal
>\w+</literal
>), за якими слідують ще пробіли (<literal
>\s+</literal
>), за якими слідує символ амперсанда. У процесі пошуку було збережено ланцюжок символів абетки і амперсанд для подальшого використання під час операції з заміни. Після цього було виконано заміну знайденого відповідника нашого рядка на рядок з пробілом, за яким слідує слово <quote
>const</quote
>, за яким слідує пробіл, за яким слідує наш ланцюжок символів абетки (<literal
>\1</literal
>), за яким слідує один пробіл, за яким слідує збережений нами символ амперсанда (<literal
>\2</literal
>)</para>

<para
>Крім того, у деяких випадках ланцюжок символів абетки міг мати значення <quote
>String</quote
>, у деяких <quote
>int</quote
>, цього було досягнуто використанням класу <literal
>\w</literal
> і лічильника <literal
>+</literal
>.</para>

</example>

</listitem>

</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>sort</command
></cmdsynopsis
></term>
<listitem
><para
>Впорядковує позначений фрагмент тексту або весь текст у документі.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>natsort</command
></cmdsynopsis
></term>
<listitem
><para
>Впорядковує позначені рядки або увесь документ у природному порядку.</para>

<example>
<title
><command
>sort</command
> порівняно з <command
>natsort</command
></title>
<para
><userinput
>sort(a10, a1, a2)</userinput
> виведе <computeroutput
>a1, a10, a2</computeroutput
></para>
<para
><command
>natsort(a10, a1, a2)</command
> виведе <computeroutput
>a1, a2, a10</computeroutput
></para>
</example
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>moveLinesDown</command
></cmdsynopsis
></term>
<listitem
><para
>Пересунути позначені рядки нижче.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>moveLinesUp</command
></cmdsynopsis
></term>
<listitem
><para
>Пересунути позначені рядки вище.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>uniq</command
></cmdsynopsis
></term>
<listitem
><para
>Вилучити рядки-дублікати з позначеного фрагмента тексту або всього документа.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>rtrim</command
></cmdsynopsis
></term>
<listitem
><para
>Вилучити кінцевий пробіл з позначеного фрагмента тексту або всього документа.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>ltrim</command
></cmdsynopsis
></term>
<listitem
><para
>Вилучити початковий пробіл з позначеного фрагмента тексту або всього документа.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>join</command
><arg choice="opt"
>STRING роздільник</arg
></cmdsynopsis
></term>
<listitem
><para
>Об’єднати позначені рядки або рядки у всьому документі. Додатково можна визначити роздільник, наприклад: <userinput
><command
>join</command
> ', '</userinput
> </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>rmblank</command
></cmdsynopsis
></term>
<listitem
><para
>Вилучити всі пробіли з позначеного фрагмента тексту або всього документа.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>unwrap</command
></cmdsynopsis
></term>
<listitem
><para
>Скасувати перенесення рядків у позначеному фрагменті тексту або всьому документі.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>each</command
><arg choice="req"
>STRING скрипт</arg
></cmdsynopsis
></term>
<listitem
><para
>Викликати вказану як аргумент функцію JavaScript для обробки списку (позначених) рядків і замінити їх повернутим значенням виклику.</para>

<example>
<title
>Об’єднати позначені рядки</title>
<para
><userinput
><command
>each</command
> 'function(lines){return lines.join(", ")}' </userinput
></para>

<para
>Або коротше:</para>
<para
><userinput
><command
>each</command
> 'lines.join(", ")'</userinput
></para>
</example>

</listitem>
</varlistentry>



<varlistentry>
<term
><cmdsynopsis
><command
>filter</command
><arg choice="req"
>STRING скрипт</arg
></cmdsynopsis
></term>
<listitem
><para
>Викликати вказану як аргумент функцію JavaScript для обробки списку (позначених) рядків і вилучити ті з них, для яких буде повернуто false.</para>

<example>
<title
>Вилучити порожні рядки</title>
<para
><userinput
><command
>filter</command
> 'function(1){return 1.length 
> 0;}' </userinput
></para>

<para
>Або коротше:</para>
<para
><userinput
><command
>filter</command
> 'line.length 
> 0'</userinput
></para>
</example>

</listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>map</command
><arg choice="req"
>STRING скрипт</arg
></cmdsynopsis
></term>
<listitem
><para
>Викликати вказану як аргумент функцію JavaScript для обробки списку (позначених) рядків і замінити рядок значенням, яке буде повернуто у відповідь на виклик.</para>

<example>
<title
>Вилучити порожні рядки</title>
<para
><userinput
><command
>map</command
> 'function(line){return line.replace(/^s+/,"");}' </userinput
></para>

<para
>Або коротше:</para>
<para
><userinput
><command
>map</command
> 'line.replace(/^s+/,"")'</userinput
></para>
</example>

</listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>duplicateLinesUp</command
></cmdsynopsis
></term>
<listitem
><para
>Здублювати позначені рядки над поточним позначеним фрагментом.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>duplicateLinesDown</command
></cmdsynopsis
></term>
<listitem
><para
>Здублювати позначені рядки під поточним позначеним фрагментом.</para>
</listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3 id="advanced-editing-tools-commandline-commands-navigation">
<title
>Команди навігації</title>

<variablelist>

<varlistentry>
<term
><cmdsynopsis
><command
>goto</command
><arg choice="req"
>INT рядок</arg
></cmdsynopsis
></term>
<listitem
><para
>За допомогою цієї команди можна перейти до вказаного рядка.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>grep</command
> <arg choice="req"
>STRING шаблон</arg
> </cmdsynopsis
></term>
<listitem
><para
>Знайти у документі рядки, що відповідають формальному виразу <userinput
>шаблон</userinput
>. Щоб дізнатися більше, зверніться до розділу <xref linkend="regular-expressions"/>.</para>
</listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>find</command
><arg choice="req"
>STRING шаблон</arg
></cmdsynopsis
></term>
<listitem
><para
>За допомогою цієї команди можна перейти до першого відповідника рядка <userinput
>шаблон</userinput
> у тексті, відповідно до налаштувань. Перейти до наступних відповідників можна за допомогою пункту меню <menuchoice
><guimenu
>Зміни</guimenu
><guimenuitem
>Знайти далі</guimenuitem
></menuchoice
> (типовим клавіатурним скороченням є <keycap
>F3</keycap
>).</para>
<para
>Команду пошуку можна налаштувати додаванням двокрапки, за якою можна вказати один або декілька параметрів, у формі <userinput
>find:параметри шаблон</userinput
>. Серед можливих параметрів:</para>

<variablelist>

<varlistentry>
<term
><userinput
>b</userinput
></term>
<listitem
><para
>Пошук назад.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>c</userinput
></term>
<listitem
><para
>Шукати від позиції курсора.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>e</userinput
></term>
<listitem
><para
>Шукати лише у позначеному фрагменті.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>r</userinput
></term>
<listitem
><para
>Пошук за формальним виразом. Якщо встановлено цей прапорець, ви зможете використовувати параметр <userinput
>\N</userinput
>, де N — номер підрядка у рядку «замінник».</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>s</userinput
></term>
<listitem
><para
>Виконати пошук з врахуванням регістру.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>w</userinput
></term>
<listitem
><para
>Шукати лише цілі слова.</para
></listitem>
</varlistentry>

</variablelist>
</listitem>

</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>ifind</command
><arg choice="req"
>STRING шаблон</arg
></cmdsynopsis
></term>
<listitem
><para
>За допомогою цієї команди можна виконати <quote
>інтерактивний</quote
> пошук. Ви можете налаштувати пошук додаванням одного або декількох параметрів після символу двокрапки, ось так: <userinput
>ifind:параметри шаблон</userinput
>. Серед можливих параметрів: <variablelist>
<varlistentry>
<term
><userinput
>b</userinput
></term>
<listitem
><para
>Пошук назад.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>r</userinput
></term>
<listitem
><para
>Виконати пошук за вказаним формальним виразом.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>s</userinput
></term>
<listitem
><para
>Виконати пошук з врахуванням регістру.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><userinput
>c</userinput
></term>
<listitem
><para
>Шукати від позиції курсора.</para
></listitem>
</varlistentry>

</variablelist>
</para
></listitem>
</varlistentry>

</variablelist>

</sect3>


<sect3 id="advanced-editing-tools-commandline-commands-basic">
<title
>Команди базового керування редактором (залежать від використаного у програмі компонента редактора)</title>

<variablelist>

<varlistentry>
<term
><cmdsynopsis
><command
>w</command
></cmdsynopsis
></term>
<listitem
><para
>Зберегти поточний документ.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>wa</command
></cmdsynopsis
></term>
<listitem
><para
>Зберегти всі поточні відкриті документи.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>q</command
></cmdsynopsis
></term>
<listitem
><para
>Закрити поточний документ.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>qa</command
></cmdsynopsis
></term>
<listitem
><para
>Закрити всі відкриті документи.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>wq</command
></cmdsynopsis
></term>
<listitem
><para
>Зберегти і закрити поточний документ.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>wqa</command
></cmdsynopsis
></term>
<listitem
><para
>Зберегти і закрити всі поточні відкриті документи.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>x</command
></cmdsynopsis
></term>
<listitem
><para
>Зберегти і закрити поточний документ, лише якщо його було змінено. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>x</command
></cmdsynopsis
></term>
<listitem
><para
>Зберегти і закрити всі поточні відкриті документ, лише якщо до них було внесено зміни.</para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>bp</command
></cmdsynopsis
></term>
<listitem
><para
>Перейти до попереднього документа у списку документів. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>bn</command
></cmdsynopsis
></term>
<listitem
><para
>Перейти до наступного документа у списку документів. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>new</command
></cmdsynopsis
></term>
<listitem
><para
>Відкрити новий документ на новій панелі, створеній горизонтальним поділом поточної панелі редагування. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>vnew</command
></cmdsynopsis
></term>
<listitem
><para
>Відкрити новий документ на новій панелі, створеній вертикальним поділом поточної панелі редагування. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>e</command
></cmdsynopsis
></term>
<listitem
><para
>Перезавантажити поточний документ, якщо його було змінено на диску. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>enew</command
></cmdsynopsis
></term>
<listitem
><para
>Редагувати новий документ. </para
></listitem>
</varlistentry>

<varlistentry>
<term
><cmdsynopsis
><command
>print</command
></cmdsynopsis
></term>
<listitem
><para
>Відкрити діалогове вікно друку, за допомогою якого ви зможете надрукувати поточний документ. </para
></listitem>
</varlistentry>

</variablelist>

</sect3>


</sect2>

</sect1>

<sect1 id="advanced-editing-tools-code-folding">
<title
>Використання обгортки коду</title>

<para
>За допомогою згортання коду ви можете приховувати частини документа у вікні редактора: так легше працювати з великими документами. У &kappname; діапазони рядків, придатні для згортання, визначаються правилами підсвічування синтаксису, тому згортання можливе не для всіх форматів файлів, — типово, згортання працює у коді програм, розмітки XML та подібних форматів. Під час редагування коду визначення підсвічування також можна вручну визначати діапазони згортання, зазвичай, такі діапазони визначаються за допомогою ключових слів <userinput
>BEGIN</userinput
> і <userinput
>END</userinput
>.</para>

<para
>Щоб скористатися можливостями згортання, слід задіяти позначки згортання за допомогою пункту меню <menuchoice
><guimenu
>Перегляд</guimenu
> <guimenuitem
>Показувати маркери згортання</guimenuitem
></menuchoice
>, якщо цих позначок ще не показано у вікні редактора. На панелі позначок згортання з лівого боку екрана буде показано у графічному вигляді діапазони рядків, які можна згорнути. Символи-трикутники позначатимуть можливі дії з вказаним діапазоном: трикутник, вершина якого вказує вниз, означатиме розгорнутий діапазон рядків, — натискання позначки трикутника призведе до згортання діапазону, — тепер програма показуватиме трикутник з вершиною, спрямованою праворуч.</para>

<para
>Передбачено одинадцять пунктів меню, за допомогою яких можна керувати станом областей згортання коду, їх перелік можна знайти у <link linkend="view-code-folding"
>розділі, присвяченому меню</link
>. </para>

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

<para
>Якщо ви не бажаєте користуватися можливістю згортання коду, ви можете зняти позначку з пункту <guilabel
>Показувати маркери згортання (якщо наявні)</guilabel
> на сторінці <link linkend="appearance"
>Вигляд</link
> налаштування редактора.</para>

</sect1>

<sect1 id="advanced-editing-tools-scripting">
<title
>Розширення можливостей &kappname; за допомогою скриптів</title>

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

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

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

<para
>У наступних розділах наведено покрокові настанови щодо створення основи простого інструменту відступів. На першому кроці вам слід створити файл <filename
>*.js</filename
> з назвою, наприклад, <filename
>javascript.js</filename
> у локальній домашній теці <filename
>$KDEHOME/share/apps/katepart/indentation</filename
>. </para>

<sect3 id="advanced-editing-tools-scripting-indentation-header">
<title
>Заголовок скрипту додавання відступів</title>
<para
>Заголовок файла <filename
>javascript.js</filename
> подається у межах закоментованого блоку і має таку форму <programlisting>
/* kate-script
 * name: JavaScript
 * author: Example Name &lt;example.name@some.address.org&gt;
 * license: BSD
 * revision: 1
 * kate-version: 3.4
 * required-syntax-style: javascript
 * indent-languages: javascript
 * priority: 0
 * i18n-catalog: mycatalog
 *
 * A line without colon ':' stops header parsing. That is, you can add optional
 * text here such as a detailed license.
 */
</programlisting
> Нижче ми зупинимося докладніше на кожному з записів заголовка. <itemizedlist>
<listitem
><para
><literal
>kate-script</literal
> [обов’язковий запис]: цей текст слід додавати у першому рядку файла <filename
>*.js</filename
>, інакше &kappname; просто відмовиться обробляти скрипт. </para
></listitem>
<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
> [необов’язковий запис]: відокремлений комами список потрібних для роботи скрипту стилів підсвічування синтаксичних конструкцій. Цей запис є важливим для інструментів відступів, які працюють на основі певних даних щодо підсвічування у документі. Якщо буде вказано стиль синтаксичних конструкцій, інструментом відступів можна буде скористатися, лише якщо буде задіяно відповідний інструмент підсвічування тексту. Таким чином можна запобігти «невизначеній поведінці», спричиненій використанням інструменту відступів без потрібної для його роботи схеми підсвічування. Наприклад, у такий спосіб налаштовано інструмент відступів Ruby у файлах <filename
>ruby.js</filename
> і <filename
>ruby.xml</filename
>. </para
></listitem>
<listitem
><para
><literal
>indent-languages</literal
> [необов’язковий запис]: відокремлений комами список стилів синтаксичних конструкцій, які може обробляти інструмент відступів, наприклад c++, java. </para
></listitem>
<listitem
><para
><literal
>priority</literal
> [необов’язковий запис]: якщо якомусь файлу з визначеним підсвічуванням синтаксичних конструкцій відповідає декілька інструментів відступів, за допомогою цього запису буде встановлено пріоритет застосування інструменту відступів. </para
></listitem>
<listitem
><para
><literal
>i18n-catalog</literal
> [необов’язковий]: додатковий каталог повідомлень (файл <literal
>po</literal
>), завантажений для перекладу сторонніх інструментів відступів.</para
></listitem>
</itemizedlist>
</para>

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

</sect3>

<sect3 id="advanced-editing-tools-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
>$KDEDIR/share/apps/katepart/script/indentation</filename
>. </para>

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

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

</sect3>
</sect2>

<sect2 id="advanced-editing-tools-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
>$KDEHOME/share/apps/katepart/script/commands</filename
>. </para>

<sect3 id="advanced-editing-tools-scripting-command-line-header">
<title
>Заголовок скрипту командного рядка</title>
<para
>Заголовок файла <filename
>javascript.js</filename
> подається у межах закоментованого блоку і має таку форму <programlisting>
/* kate-script
 * author: Example Name &lt;example.name@some.address.org&gt;
 * license: BSD
 * revision: 1
 * kate-version: 3.4
 * functions: sort, format-paragraph
 * i18n-catalog: mycatalog
 *
 * A line without colon ':' stops header parsing. That is, you can add optional
 * text here such as a detailed license.
 */
</programlisting
> Нижче наведено докладніший опис кожного з записів заголовка. <itemizedlist>
<listitem
><para
><literal
>kate-script</literal
> [обов’язковий запис]: цей текст слід додавати у першому рядку файла <filename
>*.js</filename
>, інакше &kappname; просто відмовиться обробляти скрипт.</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
>functions</literal
> [обов’язковий запис]: відокремлений комами список команд скрипту.</para
></listitem>
<listitem
><para
><literal
>i18n-catalog</literal
> [необов’язковий]: додатковий каталог повідомлень (файл <literal
>po</literal
>), завантажений для перекладу сторонніх скриптів.</para
></listitem>
</itemizedlist>
</para>

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

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

<para
>Всі оголошені у заголовку функції має бути реалізовано у тілі скрипту. Наприклад, у файлі скрипту з наведеного вище прикладу слід реалізувати дві функції, <command
>sort</command
> і <command
>format-paragraph</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>

<sect4 id="advanced-editing-tools-scripting-command-line-shortcuts">
<title
>Призначення клавіатурних скорочень</title>
<para
>Призначення клавіатурних скорочень стане можливим, лише якщо у вашому скрипті є функція з назвою <literal
>action</literal
> у такому форматі: <programlisting>
function action(cmd)
{
    var a = new Object();
    if (cmd == "sort") {
        a.text = i18n("Sort Selected Text");
        a.icon = "";
        a.category = "";
        a.interactive = false;
        a.shortcut = "";
    } else if (cmd == "moveLinesDown") {
        // same for next action
    }
    return a;
}
</programlisting
> Параметр <literal
>cmd</literal
> цієї функції визначає команду, виконання якої буде пов’язано з клавіатурним скороченням. Для повернутого об’єкта javascript має бути визначено декілька значень полів: <itemizedlist>
<listitem
><para
><literal
>a.text</literal
> [обов’язковий запис]: це текст пункту, який буде показано у меню <menuchoice
><guimenu
>Інструменти</guimenu
><guisubmenu
>Скрипти</guisubmenu
></menuchoice
>. Не забудьте вказати  <literal
>i18n</literal
> для перекладу.</para
></listitem>
<listitem
><para
><literal
>a.icon</literal
> [необов’язковий запис]: піктограма, яку буде показано поряд з текстом пункту меню. Можна використовувати назву будь-якої з піктограм KDE.</para
></listitem>
<listitem
><para
><literal
>a.category</literal
> [необов’язковий запис]: якщо буде вказано категорію, пункт скрипту буде додано у підменю. Не забудьте використати <literal
>i18n</literal
>, щоб уможливити переклад.</para
></listitem>
<listitem
><para
><literal
>a.interactive</literal
> [необов’язковий]: якщо для роботи скрипту потрібні дані, введені користувачем, встановіть значення <literal
>true</literal
>.</para
></listitem>
<listitem
><para
><literal
>a.shortcut</literal
> [необов’язковий запис]: клавіатурне скорочення, вказане за допомогою цього значення буде типовим. Приклад: Ctrl+Alt+t. Докладніше про можливі скорочення можна дізнатися з <ulink url="http://doc.qt.nokia.com/latest/qt.html#Key-enum"
>документації до Qt</ulink
>.</para
></listitem>
</itemizedlist>
</para>


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

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

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

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

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

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

</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="advanced-editing-tools-scripting-api-prototypes">
<title
>Курсори і діапазони</title>

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

<sect4 id="advanced-editing-tools-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
>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="advanced-editing-tools-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.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
>bool 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="advanced-editing-tools-scripting-api-global">
<title
>Загальні функції (Global Functions)</title>
<para
>У цьому розділі наведено всі загальні функції.</para>


<sect4 id="advanced-editing-tools-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="advanced-editing-tools-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="advanced-editing-tools-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, вам слід подбати про видобування і переклад повідомлень власноруч. Разом зі скриптами вам слід поширювати і файли перекладів, які міститимуть всі придатні для перекладу рядки. Крім того, у заголовку вашого скрипту має бути явним чином вказано каталог перекладів, який слід завантажити. Зробити це можна за допомогою параметра <literal
>i18n-catalog</literal
>. </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="advanced-editing-tools-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="advanced-editing-tools-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
>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
>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
>String 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>
