&Anders.Lund; &Anders.Lund.mail;
&Dominik.Haumann; &Dominik.Haumann.mail;
Юрій
Чорноіван

    yurchor@ukr.net

Переклад українською

# Додаткові інструменти редагування

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

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

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

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

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

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

Щоб додати позначки коментарів, скористайтеся пунктом меню Інструменти Закоментувати або відповідною комбінацією клавіш, типовою комбінацією є &Ctrl;D.

Щоб вилучити позначки коментарів, скористайтеся пунктом меню Інструменти Розкоментувати або відповідною комбінацією клавіш, типовою комбінацією є &Ctrl;&Shift;D.

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

У компонент редактора Kate вбудовано інструмент для роботи з командним рядком, за допомогою якого ви зможете виконувати різноманітні дії за мінімального графічного інтерфейсу. Командний рядок — це текстова панель у нижній частині вікна редактора, щоб увімкнути показ цієї панелі скористайтеся пунктом меню Перегляд Перемкнутися в командний рядок або скористайтеся клавіатурним скороченням (типовим клавіатурним скороченням є F7). У редакторі передбачено набір команд, документацію з яких наведено нижче, та додаткові команди, за допомогою яких можна керувати додатками до програми.

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

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

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

### Стандартні команди командного рядка

#### Команди налаштування редактора

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

##### Типи аргументів

BOOLEAN

  Цей тип використовується для команд, які вмикають або вимикаю певні налаштування. Можливими значеннями таких параметрів є `on`, `off`, `true`, `false`, `1` і `0`

INTEGER

  Ціле число

STRING

  Рядок

    set-tab-widthINTEGER ширина

  Встановлює ширину табуляції у значення `ширина`

    set-indent-widthINTEGER ширина

  Встановлює відступ у значення кількості пробілів, визначене параметром `ширина`. Використовується, лише якщо увімкнено відступи з пробілів.

    set-word-wrap-columnINTEGER довжина

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

    set-icon-borderBOOLEAN вмикання

  Встановлює видимість бічної смужки піктограм.

    set-folding-markersBOOLEAN вмикання

  Встановлює значення видимості позначок панелі згортання.

    set-line-numbersBOOLEAN вмикання

  Встановлює значення видимості панелі номерів рядків.

    set-replace-tabsBOOLEAN вмикання

  Якщо має значення «true», введені вами знаки табуляції буде замінено пробілами.

    set-remove-trailing-spaceBOOLEAN вмикання

  Якщо цей параметр буде увімкнено, після переведення курсора на інших рядок пробіли наприкінці поточного рядка вилучатимуться.

    set-show-tabsBOOLEAN вмикання

  Якщо буде увімкнено цей параметр, символи табуляції і пробіли наприкінці рядка буде показано у вигляді маленьких крапок.

    set-indent-spacesBOOLEAN вмикання

  Якщо буде увімкнено цей параметр, редактор робитиме відступ на `indent-width` пробілів, замість символу табуляції, під час переходу на наступний рівень відступу.

    set-mixed-indentBOOLEAN вмикання

  Якщо буде увімкнено цей параметр, kate використовуватиме суміш з символів табуляції і пробілів для додавання відступів. Ширина кожного з рівнів відступу визначатиметься значенням параметра `indent-width`, загальний же відступ буде оптимізовано так, щоб у ньому використовувалася максимальна кількість символів табуляції.

  Після виконання цієї команди буде увімкнено створення відступів пробілами, якщо ширину відступу не було вказано, буде встановлено значення ширини відступу у половину значення параметра документа `tab-width` на час виконання команди.

    set-word-wrapBOOLEAN вмикання

  Встановлює значення для динамічного перенесення слів у `вмикання` (true або false)

    set-replace-tabs-saveBOOLEAN вмикання

  Якщо увімкнути цей параметр, під час збереження документа символи табуляції буде замінено на пробіли.

    set-remove-trailing-space-saveBOOLEAN вмикання

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

    set-indent-modeназва

  Встановлює режим автоматичного встановлення відступів у значення `назва`. Якщо програмі не вдасться розпізнати параметр `назва`, буде встановлено режим 'none'. Коректними значеннями режиму є 'cstyle', 'csands', 'xml', 'python', 'varindent' і 'none'.

    set-highlightпідсвічування

  Визначає систему підсвічування синтаксису для поточного документа. Параметром команди має бути коректна назва підсвічування у тому вигляді, у якому ця система фігурує у меню Інструменти Підсвічування. У цій команді передбачено автоматичне доповнення параметра за списком.

#### Команди редагування

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

    indent

  Додає відступ у виділені рядки або поточний рядок.

    unindent

  Вилучає початковий відступ з виділених рядків або поточного рядка.

    cleanindent

  Вилучає відступи для виділених рядків або поточного рядка відповідно до параметрів відступів поточного документа.

    comment

  Додає позначки коментаря, які роблять виділений фрагмент тексту, виділені рядки або поточний рядок коментарями, відповідно до формату тексту, який визначено у параметрах підсвічування синтаксису поточного документа.

    uncomment

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

    kill-line

  Вилучає поточний рядок.

    replaceшаблонзамінник

  Замінює текст, що відповідає `шаблону`, на текст, вказаний у `заміннику`. Якщо вам потрібно включити пробіл у `шаблон`, вам слід взяти як `шаблон`, так і `замінник` у одинарні або подвійні лапки. Якщо у команді не буде лапок, перше зі слів-параметрів вважатиметься `шаблоном`, а решта — `замінником`. Якщо параметр `замінник` буде порожнім, всі рядки, які відповідають `шаблону` буде вилучено з тексту.

  Ви можете вказати прапорці налаштування пошуку за допомогою додавання двокрапки, за якою слід вказати одну або декілька літер, кожна з яких відповідатиме за налаштування. Команда викладатиме так: `replace:параметри шаблон замінник`. Можливі параметри:

  `b`

    Пошук назад.

  `c`

    Шукати від позиції курсора.

  `e`

    Шукати лише у виділеному фрагменті.

  `r`

    Пошук за формальним виразом. Якщо встановлено цей прапорець, ви зможете використовувати параметр `\N`, де N — номер підрядка у рядку «замінник».

  `s`

    Виконати пошук з врахуванням регістру.

  `p`

    Запитувати дозвіл на заміну наступного елемента.

  `w`

    Шукати лише цілі слова.

    dateформат

  Вставляє дату/час у форматі, визначеному параметром `формат`, або у форматі yyyy-MM-dd hh:mm:ss, якщо рядок формату не буде вказано. Під час обробки рядка `формат` буде використано такі перетворення:

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

    charідентифікатор

  За допомогою цієї команди можна вводити символи за їх числовими ідентифікаторами у десятковій, вісімковій або шістнадцятковій формі. Щоб скористатися нею, відкрийте діалогове вікно редагування команди і введіть команду `char: [число]` у поле для введення, а потім натисніть кнопку Гаразд.

  ##### Приклади команди `char`

  Ввід: `char:234`

  Вивід: `ê`

  Ввід: `char:0x1234`

  Вивід: `ሴ`

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

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

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

  Щоб знайти символ `(` або символ `)`, вам слід екранувати ці символи за допомогою зворотної навскісної риски: `\(\)`

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

  ##### Заміна тексту у поточному рядку

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

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

  ##### Заміна тексту у всьому файлі

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

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

  ##### Складніший приклад

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

  Припустімо, що у вас є такий рядок:

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

  Тепер вам здається, що цей код виглядає кострубато: ви вирішили скористатися ключовим словом `const` для всіх параметрів address of, у яких назві аргументу передує оператор &. Ви також бажаєте вилучити зайві пробіли так, щоб між будь-якими двома словами був лише один символ пробілу.

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

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

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

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

#### Команди навігації

    gotoINT рядок

  За допомогою цієї команди можна перейти до вказаного рядка.

    findшаблон

  За допомогою цієї команди можна перейти до першого відповідника рядка `шаблон` у тексті, згідно до налаштувань. Перейти до наступних відповідників можна за допомогою пункту меню Правка Знайти далі (типовим клавіатурним скороченням є F3).

  Команду пошуку можна налаштувати додаванням двокрапки, за якою можна вказати один або декілька параметрів, у формі `find:параметри шаблон`. Серед можливих параметрів:

  `b`

    Пошук назад.

  `c`

    Шукати від позиції курсора.

  `e`

    Шукати лише у виділеному фрагменті.

  `r`

    Пошук за формальним виразом. Якщо встановлено цей прапорець, ви зможете використовувати параметр `\N`, де N — номер підрядка у рядку «замінник».

  `s`

    Виконати пошук з врахуванням регістру.

  `w`

    Шукати лише цілі слова.

    ifindшаблон

  За допомогою цієї команди можна виконати інтерактивний пошук. Ви можете налаштувати пошук додаванням одного або декількох параметрів після символу двокрапки, ось так: `ifind:параметри шаблон`. Серед можливих параметрів:

  `b`

    Пошук назад.

  `r`

    Виконати пошук за вказаним формальним виразом.

  `s`

    Виконати пошук з врахуванням регістру.

  `c`

    Шукати від позиції курсора.

## Використання обгортки коду

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

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

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

Якщо ви не бажаєте користуватися можливістю згортання коду, ви можете зняти позначку з пункту Показувати маркери згортання (якщо наявні) на сторінці Вигляд налаштування редактора.

## Написання скриптів для компонента редактора на Javascript

### Вступ

Починаючи з версії 2.5, компонент редактора &kate; підтримує роботу скриптів ECMA, які також відомі під назвою JavaScript.

Використовувати скрипти можна лише за допомогою вбудованого командного рядка. Потрібно також, щоб файл скрипту разом з необов’язковим файлом .desktop, у якому визначено відповідні властивості, знаходився у теці, де &kate; може його знайти. Відповідна тека має назву `katepart/scripts` і знаходиться у теці даних &kde;. Визначити адресу тек даних можна за допомогою команди `kde4-config `--path` `data`` Зазвичай, існує принаймні дві такі теки: тека системних даних і тека особистих даних. Звичайно ж, скрипти теки системних даних доступні для всіх користувачів системи, а скрипти з особистої теки доступні лише вашому користувачеві.

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

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

У поточній версії ще не передбачено способів передачі значень параметрів вашим скриптам. Зачекайте, це, можливо, буде реалізовано у світлому майбутньому ;)

### Програмний інтерфейс Kate для JavaScript

У цьому розділі ви знайдете повний набір функцій і властивостей, які можна використовувати у об’єктах document і view. Крім того, ви, звичайно ж, можете користуватися стандартними об’єктами на зразок Math, String Regex тощо.

Під час запуску скрипту об’єктом `document` буде поточний документ, а об’єктом `view` буде поточний перегляд.

Типи аргументів, звичайно ж, поки що не використовуються у JavaScript, їх наведено лише для того, щоб ви бачили, які значення очікує отримати функція.

#### Загальні функції

`debug( `рядок`) [функція]`

  #### параметри

  - `рядок` — рядок для виводу

  Виводить рядок до STDERR за допомогою `kDebug()`. Призначену для виводу область буде використано для виводу даних, до яких буде додано префікс `Kate (KJS Scripts):`

#### Інтерфейс прикладних програм `document`

`document.attribute( `рядок` , `позиція` ); [функція]`

  #### Параметри

  - `uint рядок` — рядок позиції, для якої слід визначити атрибут.

  - `uint стовпчик` — стовпчик позиції, для якої слід визначити атрибут.

  Повертає числовий ідентифікатор атрибута для позиції у документі [`рядок`,`стовпчик`]. Атрибут відповідає вигляду або стилю тексту, а також використовується для обчислення підсвічування синтаксису певної частини тексту у змішаних форматах на зразок HTML або PHP.

`document.canBreakAt( `Char c`, `uint атрибут` ); [функція]`

  #### Параметри

  - `c` — символ, який слід перевірити

  - `атрибут` — атрибут на місці `c`.

  Повертає значення, яке відповідає можливості розбиття рядка на символі «c» з атрибутом «атрибут». Результат визначається за запитом до атрибута-власника підсвічування щодо того, на яких символах можливе розбиття рядка на частини.

`document.canComment( `uint атрибут_початку`, `uint атрибут_кінця` ); [функція]`

  #### Параметри

  - `атрибут_початку` — атрибут на початку діапазону рядків, який слід перетворити на коментар.

  - `атрибут_кінця` — атрибут наприкінці діапазону рядків, який слід перетворити на коментар.

  Повертає значення, яке відповідає належності атрибута_початку і атрибута_кінця до однієї системи підсвічування синтаксису. Якщо ці атрибути належать до однієї системи, підсвічування можливе.

  #### Використання canComment

      if ( document.canComment( document.attribute(1,0), document.attribute(5,0) ) ) {
          // 1,0 і 5,0 належать до одної системи підсвічування синтаксису
      }

`document.clear(); [функція]`

  Спорожнює вміст документа.

`document.commentStart( `uint атрибут` ); [функція]`

  #### Параметри

  - `атрибут` — атрибут тексту, для якого слід отримати рядок commentStart.

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

`document.commentMarker( `uint атрибут` ); [функція]`

  #### Параметри

  - `атрибут` — атрибут тексту, для якого слід отримати рядок commentMarker.

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

`document.commentEnd( `uint атрибут` ); [функція]`

  #### Параметри

  - `атрибут` — атрибут тексту, для якого слід отримати рядок commentEnd.

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

`document.editBegin(); [функція]`

  Розпочати групу команд редагування. Всі дії, виконані до виклику editEnd(), буде згруповано у дію, яку можна буде скасувати одним викликом дії «Вернути».

`document.editEnd(); [функція]`

  Завершити групу редагування.

`document.highlightMode; [властивість: лише для читання]`

  Назва системи підсвічування синтаксису документа, на зразок JavaScript або C++. Якщо у документі не встановлено жодного режиму підсвічування, повернутим значенням буде «None». Зауважте, що вам слід використовувати назви англійською у випадках, коли ці назви відрізняються від перекладених назв.

`document.indentMode; [властивість: лише для читання]`

  Назва режиму встановлення відступів у документі, на зразок `normal` або `cstyle`. Не забувайте, якщо не встановлено жодного режиму, буде повернуто значення `none`.

`document.indentWidth; [властивість: лише для читання]`

  Довжина відступу, встановлена у документі. Використовується, якщо увімкнуто форматування відступів пробілами.

`document.insertLine( `uint рядок`, `string текст` ); [функція]`

  #### Параметри

  - `рядок` — номер рядка у документі

  - `текст` — текст, який слід вставити

  Вставляє до документа текст `текст`, починаючи з рядка `рядок`.

`document.insertText( `uint рядок`, `uint стовпчик`, `string текст` ); [функція]`

  #### Параметри

  - `рядок` — номер рядка

  - `стовпчик` — номер стовпчика

  - `текст` — текст, який слід вставити

  Вставляє текст `текст` у рядок `рядок`, починаючи зі стовпчика `стовпчик`.

document.length(); [функція]

  Повертає розмір документа у байтах.

`document.lines(); [функція]`

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

document.mixedIndent; [властивість: лише для читання]

  Булівське значення, яке відповідає значенню стану вмикання параметра мішаних відступів у документі. Якщо значенням буде «увімкнено», відступи форматуватимуться за допомогою суміші символів табуляції і пробілів так, як це робиться у редакторі Emacs.

document.removeLine( `uint рядок` ); [функція]

  #### Параметри

  - `рядок` — номер рядка

  Вилучає з документа рядок з номером `рядок`

`document.removeText( `uint початковийРядок`, `uint початковийСтовпчик`, `uint кінцевийРядок`, `uint кінцевийСтовпчик` ); [функція]`

  #### Параметри

  - `початковийРядок` визначає номер початкового рядка

  - `початковийСтовпчик` визначає номер початкового стовпчика

  - `кінцевийРядок` визначає номер кінцевого рядка

  - `кінцевийСтовпчик` визначає номер кінцевого стовпчика

  Вилучає фрагмент тексту від позиції `початковийРядок`, `початковийСтовпчик` до позиції `кінцевийРядок`, `кінцевийСтовпчик`.

`document.setText( `string текст` ); [функція]`

  #### Параметри

  - `текст` — текст документа

  Замінює весь вміст документа на `текст`.

`document.spaceIndent; [властивість: лише читання]`

  Булівське значення, за яким можна визначити чи було увімкнуто форматування відступів пробілами у документі. Якщо таке форматування було увімкнено, відступи у документі створюватимуться додаванням до відступу попереднього рівня indentWidth пробілів, у іншому випадку для кожного наступного рівня додаватиметься символ табуляції.

`document.textFull(); [функція]`

  Повертає повний текст документа. Якщо текст складатиметься з декількох рядків символом переведення рядка буде `\n`.

`document.textLine( uint рядок ); [функція]`

  #### Параметри

  - `рядок` — номер рядка

  Повертає текст рядка з номером `рядок`.

`document.textRange( `uint початковийРядок`, `uint початковийСтовпчик`, `uint кінцевийРядок`, `uint кінцевийСтовпчик` ); [функція]`

  #### Параметри

  - `початковийРядок` визначає номер початкового рядка

  - `початковийСтовпчик` визначає номер початкового стовпчика

  - `кінцевийРядок` визначає номер кінцевого рядка

  - `кінцевийСтовпчик` визначає номер кінцевого стовпчика

  Повертає вказаний фрагмент тексту. Якщо текст складатиметься з декількох рядків символом переведення рядка буде `\n`.

#### Програмний інтерфейс `view`

`view.clearSelection(); [функція]`

  Скасовує всі виділення тексту.

`view.cursorColumn(); [функція]`

  Повертає номер стовпчика, де зараз знаходиться курсор (символ табуляції під час підрахунку розбивається на пробіли).

`view.cursorColumnReal(); [функція]`

  Повертає дійсний номер стовпчика, де зараз знаходиться курсор (символ табуляції під час підрахунку вважається одиничним символом).

`view.cursorLine(); [функція]`

  Повертає номер рядка, у якому знаходиться курсор.

`view.hasSelection(); [функція]`

  Повертає `true`, якщо у області перегляду міститься виділений текст, у іншому випадку повертає `false`.

`view.removeSelectedText(); [функція]`

  Вилучає виділений текст, якщо у області перегляду було виділено фрагмент тексту.

`view.selectAll(); [функція]`

  Виділяє весь текст документа.

`view.selection(); [функція]`

  Повертає виділений у документі текст. Якщо текст складатиметься з декількох рядків символом переведення рядка буде `\n`.

`view.selectionEndColumn; [властивість: лише читання]`

  Повертає номер завершального стовпчика у виділеному фрагменті.

`view.selectionEndLine; [властивість: лише читання]`

  Повертає номер завершального рядка у виділеному фрагменті.

`view.selectionStartColumn; [властивість: лише читання]`

  Повертає номер початкового стовпчика у виділеному фрагменті.

`view.selectionStartLine; [властивість: лише читання]`

  Повертає номер початкового рядка виділеного фрагмента тексту.

`view.setCursorPosition( `uint рядок`, `uint стовпчик` ); [функція]`

  #### Параметри

  - `рядок` вказує рядок для курсора.

  - `стовпчик` вказує стовпчик для курсора.

  Переводить курсор введення тексту у позицію [`рядок`, `стовпчик`]. Переведення здійснюватиметься у візуальному сенсі: символ табуляції вважатиметься сукупністю tabwidth символів, залежно від позиції у рядку. Нову позицію курсора буде показано у області перегляду. Відлік рядків і стовпчиків починається з нуля.

`view.setCursorPositionReal( `uint рядок`, `uint стовпчик` ); [функція]`

  #### Параметри

  - `рядок` вказує рядок для курсора.

  - `стовпчик` вказує стовпчик для курсора.

  Переводить курсор введення тексту у позицію [`рядок`, `стовпчик`]. Значення позиції визначатимуться за кількістю символів у рядку: символ табуляції вважатиметься одним символом. Нову позицію курсора буде показано у області перегляду. Відлік рядків і стовпчиків починається з нуля.

`view.setSelection( `uint початковийРядок`, `uint початковийСтовпчик`, `uint кінцевийРядок`, `uint кінцевийСтовпчик` ); [функція]`

  #### Параметри

  - `початковийРядок` визначає номер початкового рядка

  - `початковийСтовпчик` визначає номер початкового стовпчика

  - `кінцевийРядок` визначає номер кінцевого рядка

  - `кінцевийСтовпчик` визначає номер кінцевого стовпчика

  Виділяє фрагмент тексту від рядка `початковийРядок` і стовпчика `початковийСтовпчик` до рядка `кінцевийРядок` і стовпчика `кінцевийСтовпчик`.

#### Приклад скрипту

Для прикладу, ми створимо невеличкий скрипт, який переводитиме літери у виділеному фрагменті тексту у верхній регістр. Очевидно, спочатку нам слід перевірити, чи виділено якийсь фрагмент тексту. Якщо це так, нам слід отримати текст, змінити регістр символів у ньому, а потім замінити старий текст на новий. Реалізувати ці дії можна десь так:

    if ( view.hasSelection() )
    {
      // uppercase selection
      column = view.selectionStartColumn;
      line = view.selectionStartLine;

      selection = view.selection().toUpperCase();

      document.editBegin();
      view.removeSelectedText();
      document.insertText( line, column, selection );
      document.editEnd();
    }

Щоб зібрати цю дію до групи так, щоб дію можна було скасувати одним викликом дії Вернути, ми розташуємо рядки

    view.removeSelectedText()

і

    document.insertText()

між рядками

    document.editBegin()

і

    document.editEnd()

.

#### Приклад файла `.desktop`

Ось приклад файла .desktop, який супроводжуватиме наведений вище скрипт.

    # Приклад файла .desktop
    [Desktop Entry]
    Encoding=UTF-8
    Name=Kate Part JavaScript Uppercase
    Comment=Script to uppercase the selection
    X-Kate-Command=uppercase-selection
    X-Kate-Help=<p>Usage: <code>uppercase-selection</code></p>

Як бачите, ви можете визначати кодування (Encoding), встановлювати назву (Name), коментар (Comment) і текст довідки за допомогою X-Kate-Help, а також назву команди через X-Kate-Command. Записи Name, Comment і X-Kate-Help буде автоматично перекладено іншими мовами командами з перекладу KDE, якщо відповідні файли буде розміщено у сховищі SVN KDE.

#### Збираємо все докупи

&kate; шукатиме у теках скриптів (див. вище) файли `*.js`. Для кожного знайденого файла програма шукатиме відповідний файл `.desktop`, наприклад, для uppercase.js виконуватиметься пошук uppercase.desktop.

Якщо файл `.desktop` не буде знайдено, скрипт буде зареєстровано у командному рядку katepart за назвою файла без суфікса .js, отже у нашому прикладі цією назвою буде `uppercase`. Якщо назви команди достатньо і вам не потрібні додаткові можливості, які забезпечуються наявністю файла `.desktop`, вам взагалі не потрібен файл `.desktop`.

Якщо існує файл `.desktop`, katepart прочитає назву, за якою скрипт було зареєстровано з запису файла .desktop X-Kate-Command, наприклад, X-Kate-Command=uppercase-selection.