# Написання скриптів

## Написання скриптів для &kile;

Можливості з роботи зі скриптами у &kile; надають змогу виконувати код мовою ECMAScript, широко відомою під назвою &javascript;. Знайти підручники щодо об’єктів (змінних), функцій та властивостей, які підтримуються &javascript; доволі просто.

Підтримку роботи зі скриптами можна увімкнути за допомогою діалогового вікна налаштування &kile;: Параметри Налаштувати Kile... Kile Запис скриптів. Вмикання або вимикання підтримки скриптів Вмикання або вимикання підтримки скриптів

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

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

- Запустити вказаний скрипт.

- Створити новий скрипт.

- Відкрити позначений скрипт у редакторі.

- Налаштувати клавіатурне скорочення для позначеного скрипту.

- Вилучити призначене клавіатурне скорочення.

- Оновити список доступних скриптів на основі даних з каталогу `$`KDEDIR`/share/apps/kile/scripts/`.

## Виконання скрипту

Виконати скрипт можна у три різних способи:

1. Вибрати потрібний скрипт і натиснути кнопку Виконати, розташовану у лівій частині віджета керування скриптами.

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

2. Скористатися клавіатурним скороченням.

   Керування скриптами: клавіатурне скорочення
   Керування скриптами: клавіатурне скорочення

   Ви можете пов’язати зі скриптом певне клавіатурне скорочення за допомогою кнопки Налаштувати панелі керування скриптами.

   Робота зі скриптами: вікно налаштування клавіатурного скорочення
   Робота зі скриптами: вікно налаштування клавіатурного скорочення

3. Використовувати послідовність символів у редакторі. Скрипт буде виконано, якщо вами буде введено відповідну послідовність символів у вікні редактора.

   Робота зі скриптами: послідовність символів у редакторі
   Робота зі скриптами: послідовність символів у редакторі

   Цей метод можна розширити для реалізації додаткових можливостей доповнення коду. Припустімо, ви написали скрипт, який просто додає команду &latex; `\textbf{}` до поточного документа.

       document.insertText("\\textbf{%C}");

   Тепер, якщо ви введете призначену послідовність символів, `bfx` у ваш текстовий документ, цю послідовність символів буде вилучено, а скрипт буде виконано. Скрипт вставить до тексту `\textbf{}` і розташує курсор між дужками.

   Робота зі скриптами: введення послідовності символів у вікні редактора
   Робота зі скриптами: введення послідовності символів у вікні редактора

   Зручний і потужний спосіб доповнення коду.

## Довідка з програмного інтерфейсу

Доступ до програмного інтерфейсу роботи зі скриптами (API), описаний у цьому розділі, можна отримати з будь-якого скрипту. До завантаження вмісту скрипту &kile; додає декілька прототипів та функцій до контексту роботи зі скриптами. Цей зручний програмний інтерфейс містить деякі прототипи, зокрема текстові курсори та визначення діапазонів тексту. Відповідін файли розташовано у теці `KILE_APP_DIR/script-plugins/`.

Скрипти &kile; трохи відрізняються від скриптів &kate;. Останні мають іншу побудову, оскільки їх можна запускати з командного рядка. Але ви можете отримати доступ до всіх функцій програмного інтерфейсу &kate; з програмного інтерфейсу &kile;, отже портування коду &javascript; з &kate; до &kile; має бути доволі простим. Оскільки &kile; має дуже широкі можливості з редагування &latex;, його власний програмний інтерфейс надає доступ до набагато ширших можливостей, ніж інтерфейс &kate;.

Зауваження: опис викликів програмного інтерфейсу, які також доступні у &kate; було запозичено з документації до &kate;.

### Загальні функції (Global Functions)

У цьому розділі наведено загальні функції.

    void debug(String текст);

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

### Прототип Cursor (курсор)

Оскільки &kile; є текстовим редактором, весь програмний інтерфейс засновано на роботі з курсором і діапазонами. Тип Cursor є простим кортежем `(line, column)` (рядок, позиція), який відповідає певній позиції у тексті документа.

    Cursor();

  Конструктор. Повертає об’єкт Cursor (курсор) у позиції `(0, 0)`.

  Приклад: `var cursor = new Cursor();`

    Cursor(int рядок, int стовпчик);

  Конструктор Повертає об’єкт Cursor (курсор) у позиції (рядок, стовпчик).

  Приклад: `var cursor = new Cursor(3,42);`

    Cursor(Cursor інший);

  Конструктор копіювання Повертає копію курсора `інший`.

  Приклад: `var copy = new Cursor(other);`

    Cursor Cursor.clone();

  Повертає клон курсора.

  Приклад: `var clone = cursor.clone();`

    bool Cursor.isValid();

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

  Приклад: `var valid = cursor.isValid();`

    Cursor Cursor.invalid();

  Повертає новий некоректний курсор, розташований у позиції `(-1,-1)`.

  Приклад: `var invalidCursor = cursor.invalid();`

    int Cursor.compareTo(Cursor інший);

  Порівнює поточний курсор з курсором `інший`. Повертає

  - `-1`, якщо поточний курсор розташовано перед курсором `інший`,

  - `0`, якщо курсори у однакових позиціях і

  - `+1`, якщо поточний курсор розташовано після курсора `інший`.

    bool Cursor.equals(Cursor інший);

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

    String Cursor.toString();

  Повертає об’єкт курсора як рядок у формі `Cursor(line, column)`.

### Прототип Range (діапазон)

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

    Range();

  Конструктор: виклик `new Range()` повертає Range (діапазон) у `(0, 0) - (0, 0)`.

    Range(Cursor початок, Cursor кінець);

  Конструктор Виклик функції `new Range(початок, кінець)` повертає Range (діапазон)(`початок`, `кінець`).

    Range(int початковийРядок, int початковийСтовпчик, int кінцевийРядок, int кінцевийСтовпчик);

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

    Range(Range інший);

  Конструктор копіювання. Повертає копію Range `інший`.

    Range Range.clone();

  Повертає клон діапазону.

  Приклад: `var clone = range.clone();`

    bool Range.isValid();

  Повертає `true`, якщо початкова і кінцева позиції курсора є коректними. Якщо це не так, повертає `false`.

  Приклад: `var valid = range.isValid();`

    bool Range.invalid();

  Повертає Range (діапазон) від (-1,-1) до (-1,-1).

    bool Range.contains(Cursor курсор);

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

    bool Range.contains(Range інший);

  Повертає `true`, якщо поточний діапазон містить діапазон `інший`. Якщо це не так, повертає `false`.

    bool Range.containsColumn(int стовпчик);

  Повертає `true`, якщо `стовпчик` належить напіввідкритому інтервалу `[start.column, end.column)`. Якщо це не так, повертає `false`.

    bool Range.containsLine(int рядок);

  Повертає `true`, якщо `рядок` належить до напіввідкритого інтервалу `[start.line, end.line)`. Якщо це не так, повертає `false`.

    bool Range.overlaps(Range інший);

  Повертає `true`, якщо поточний діапазон і діапазон інший мають ненульовий перетин. Якщо це не так, повертає `false`.

    bool Range.overlapsLine(int рядок);

  Повертає `true`, якщо рядок належить до інтервалу `[start.line, end.line]`. Якщо це не так, повертає `false`.

    bool Range.overlapsColumn(int стовпчик);

  Повертає `true`, якщо стовпчик належить інтервалу `[start.column, end.column]`. Якщо це не так, повертає `false`.

    bool Range.equals(Range інший);

  Повертає `true`, якщо поточний діапазон і діапазон інший тотожні. Якщо це не так, повертає `false`.

    String Range.toString();

  Повертає діапазон у форматі `Range(Cursor(line, column), Cursor(line, column))`.

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

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

    void view.backspace();

  Програмний еквівалент натискання клавіші Backspace.

    Cursor view.cursorPosition();

  Повертає поточну позицію курсора у області перегляду.

    void view.setCursorPosition(int рядок, int стовпчик);
    void view.setCursorPosition(Cursor курсор);

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

    void view.cursorLeft();

  Пересуває курсор на одну позицію назад текстом.

    void view.cursorRight();

  Пересуває курсор на одну позицію вперед текстом.

    void view.cursorUp();

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

    void view.cursorDown();

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

    int view.cursorLine();

  Повертає номер рядка, у якому зараз перебуває курсор.

    int view.cursorColumn();

  Повертає номер позиції у рядку, у якій зараз перебуває курсор.

    void view.setCursorLine(int рядок);

  Переводить курсор у вказаний `рядок`.

    void view.setCursorColumn(int стовпчик);

  Переводить курсор у вказану позицію у рядку `стовпчик`.

    Cursor view.virtualCursorPosition();

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

    bool view.hasSelection();

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

    String view.selectedText();

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

    Range view.selectionRange();

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

    void view.setSelection(Range діапазон);

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

    void view.selectAll();

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

    void view.clearSelection();

  Знімає позначення фрагменту тексту, не вилучаючи сам текст.

    void view.removeSelectedText();

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

    void view.selectLine();

  Позначає текст у поточному рядку.

    void view.selectLine(int рядок);

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

    void view.selectLines(int з, int до);

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

    void view.selectWord();

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

    void view.selectLatexCommand();

  Позначає поточну команду &latex;. Якщо у позиції курсора немає ніяких команд, нічого не позначається.

    void view.selectEnvironment(bool всередині = false);

  Позначає весь текст у поточному середовищі &latex;. Якщо параметр `всередині` має значення `false`, буде позначено текст середовища разом з зовнішніми командами визначення &latex;, `\begin{...}...\end{...}`. Якщо ж це не так, буде позначено текст без команд визначення. Якщо функції не буде передано параметра, вважатиметься, що значенням параметра `всередині` є `false`.

    void view.selectTexgroup(bool всередині = true);

  Позначає поточну групу &latex;. Якщо параметр `всередині` має значення `true`, буде позначено групу TeX без зовнішніх дужок. Якщо не буде вказано ніякого значення параметра`всередині`, вважатиметься, що параметр має значення `true`.

    void view.selectMathgroup();

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

    void view.selectParagraph(bool всіРядки = true);

  Позначає весь текст у поточному абзаці &latex;. Якщо параметр `всіРядки` має значення `true`, до позначення буде включено перший і останній рядки абзацу повністю (разом з символом кінця рядка). Якщо для параметра буде визначено значення `false`, до позначеного фрагмента буде включено лише непробільні символи.

### Програмний інтерфейс (API) `Document`

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

    void document.insertText(String текст);

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

    void document.insertText(int рядок, int стовпчик, String текст);
    void document.insertText(Cursor курсор, String текст);

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

    bool document.removeText(int зРядка, int зіСтовпчика, int доРядка, int доСтовпчика);
    bool document.removeText(Cursor з, Cursor до);
    bool document.removeText(Range діапазон);

  Вилучає текст у вказаному діапазоні. Повертає `true` у разі успіху або `false`, якщо документ відкрито у режимі лише для читання.

    bool document.replaceText(Range діапазон, String текст);

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

    int document.lines();

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

    int document.length();

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

    Range document.documentRange();

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

    Cursor document.documentEnd();

  Повертає поточну позицію кінця документа.

    String document.text();

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

    String document.text(int зРядка, int зіСтовпчика, int доРядка, int доСтовпчика);
    String document.text(Cursor з, Cursor до);
    String document.text(Range діапазон);

  Повертає фрагмент тексту у вказаному діапазоні. Для того, щоб код було легше читати, ми рекомендуємо вам використовувати засновану на об’єктах Cursor і Range версію функції.

    bool document.setText(String текст);

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

    bool document.clear();

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

    String document.line();

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

    String document.line(int рядок);

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

    int document.lineLength();

  Повертає довжину поточного рядка.

    int document.lineLength(int рядок);

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

    bool document.insertLine(String рядок);

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

    bool document.insertLine(int рядок, String текст);

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

    bool document.removeLine();

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

    bool document.removeLine(int рядок);

  Вилучає рядок з вказаним номером. Повертає `true` у разі успіху або `false`, якщо документ відкрито у режимі лише для читання або рядка з вказаним номером у документі немає.

    bool document.replaceLine(String текст);

  Замінити текст поточного рядка вказаним текстом.

    bool document.replaceLine(int рядок, String текст);

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

    bool document.truncateLine();

  Обрізає поточний рядок на вказаному стовпчику або позиції курсора. Повертає `true` у разі успіху або `false`, якщо рядка з вказаним номером у документі немає.

    bool document.truncate(int рядок, int стовпчик);
    bool document.truncate(Cursor курсор);

  Обрізає рядок з вказаним номером на вказаному стовпчику або позиції курсора. Повертає `true` у разі успіху або `false`, якщо рядка з вказаним номером у документі немає.

    String document.word();

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

    String document.wordAt(int рядок, int стовпчик);
    String document.wordAt(Cursor курсор);

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

    Range document.wordRange();

  Повертає діапазон слова у поточній позиції курсора. Якщо у поточній позиції курсора немає жодних слів, буде повернуто значення `Range.invalid()`. Перевірку на коректність можна виконати за допомогою функції `Range.isValid()`.

    String document.latexCommand();

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

    String document.latexCommandAt(int рядок, int стовпчик);
    String document.latexCommandAt(Cursor курсор);

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

    Range document.latexCommandRange();

  Повертає діапазон команди &latex; у поточній позиції курсора. Якщо у поточній позиції курсора немає жодних команд &latex;, буде повернуто значення `Range.invalid()`. Перевірку на коректність можна виконати за допомогою функції `Range.isValid()`.

    String document.charAt(int рядок, int стовпчик);
    String document.charAt(Cursor курсор);

  Повертає символ за вказаною позицією курсора.

    String document.firstChar(int рядок);

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

    String document.lastChar(int рядок);

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

    bool document.isSpace(int рядок, int стовпчик);
    bool document.isSpace(Cursor курсор);

  Повертає `true`, якщо символ у вказаній позиції курсора є пробілом. Якщо це не так, повертає `false`.

    void document.insertBullet();

  Вставити позначку &kile;. Між такими позначками доволі просто пересуватися. Крім того, позначку буде позначено, отже її буде автоматично вилучено, щойно користувач введе першу літеру замінника цієї позначки у документі.

    void document.nextBullet();

  Перейти до наступної позначки у тексті, якщо така є.

    void document.previousBullet();

  Перейти до попередньої позначки у тексті, якщо така є.

    bool document.hasEnvironment();

  Повертає `true`, якщо було знайдено зовнішнє середовище &latex;. Якщо середовища не було знайдено, повертає `false`.

    String document.environment(bool всередині = false);

  Повертає весь текст зовнішнього середовища &latex;. Якщо для параметра `всередині` встановлено значення `false`, до тексту середовища буде включено зовнішні команди визначення &latex;, `\begin{...}...\end{...}`. У протилежному випадку буде повернуто текст без команд визначення. Якщо ніякого значення параметру не буде передано, вважатиметься, що `всередині` має значення `false`. Якщо середовища не буде знайдено, повернутий рядок буде порожнім.

    Range document.environmentRange(bool всередині = false);

  Повертає весь текст зовнішнього середовища &latex;. Якщо для параметра `всередині` встановлено значення `false`, до тексту середовища буде включено зовнішні команди визначення &latex;, `\begin{...}...\end{...}`. У протилежному випадку буде повернуто текст без команд визначення. Якщо ніякого значення параметру не буде передано, вважатиметься, що `всередині` має значення `false`. Якщо середовища не буде знайдено, буде повернуто `Range.invalid()`. Перевірити це можна за допомогою функції `Range.isValid()`.

    String document.environmentName();

  Повертає назву зовнішнього середовища &latex; або порожній рядок.

    void document.removeEnvironment(bool всередині = false);

  Вилучає текст у зовнішньому середовищі &latex;. Якщо параметр `всередині` має значення `true`, буде вилучено текст середовища разом з зовнішніми командами визначення &latex;, `\begin{...}...\end{...}`. Якщо ж це не так, буде вилучено текст без команд визначення. Якщо функції не буде передано параметра, вважатиметься, що значенням параметра `всередині` є `false`.

    void document.closeEnvironment();

  Вставити команду завершення середовища, якщо у поточній позиції курсора було виявлено незавершене середовище &latex;.

    void document.closeAllEnvironments();

  Вставити команди завершення всіх незавершених середовищ &latex;, які буде виявлено у поточній позиції курсора.

    bool document.hasTexgroup();

  Повертає `true`, якщо у поточній позиції курсора було виявлено зовнішню групу &latex;. Якщо такої групи не було виявлено, повертає `false`.

    String document.texgroup(bool всередині = true);

  Повертає весь текст зовнішньої групи &latex;. Якщо для параметра `всередині` встановлено значення `false`, до тексту середовища буде включено зовнішні дужки, `{...}`. У протилежному випадку буде повернуто текст без команд визначення. Якщо ніякого значення параметру не буде передано, вважатиметься, що `всередині` має значення `false`. Якщо групи &latex; не буде знайдено, повернутий рядок буде порожнім.

    Range document.texgroupRange(bool всередині = true);

  Повертає весь текст зовнішньої групи &latex; Якщо для параметра `всередині` встановлено значення `false`, до тексту середовища буде включено зовнішні дужки, `{...}` У протилежному випадку буде повернуто текст без дужок. Якщо ніякого значення параметру не буде передано, вважатиметься, що `всередині` має значення `false`. Якщо групи не буде знайдено, буде повернуто `Range.invalid()`. Перевірити це можна за допомогою функції `Range.isValid()`.

    void document.removeTexgroup(bool всередині = true);

  Вилучає текст у зовнішній групі &latex; Якщо параметр `всередині` має значення `true`, буде вилучено текст групи &latex; з зовнішніми дужками, `{...}`. Якщо ж це не так, буде вилучено текст без дужок. Якщо функції не буде передано параметра, вважатиметься, що значенням параметра `всередині` є `false`.

    bool document.hasMathgroup();

  Повертає `true`, якщо у поточній позиції курсора було виявлено зовнішню формульну групу &latex;. Якщо такої групи не було виявлено, повертає `false`.

    String document.mathgroup();

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

    Range document.mathgroupRange();

  Повертає діапазон зовнішньої формульної групи &latex; у поточній позиції курсора. Якщо у поточній позиції курсора немає формульних груп, буде повернуто значення `Range.invalid()`. Перевірку на коректність можна виконати за допомогою функції `Range.isValid()`.

    void document.removeMathgroup();

  Вилучити текст зовнішньої формульної групи &latex;.

    String document.paragraph();

  Повернути текст поточного абзацу &latex;.

    Range document.paragraphRange();

  Повернути діапазон зовнішнього параграфа &latex;.

    void document.removeParagraph();

  Вилучити текст поточного параграфа &latex;.

    bool document.matchesAt(int рядок, int стовпчик, String текст);
    bool document.matchesAt(Cursor курсор, String текст);

  Повертає `true`, якщо вказаний `текст` розташовано за відповідною позицією курсора. Якщо це не так, повертає `false`.

    bool document.startsWith(int рядок, String шаблон, bool пропускатиПробіли = true);

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

    bool document.endsWith(int рядок, String шаблон, bool пропускатиПробіли = true);

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

    int document.firstColumn(int рядок);

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

    int document.lastColumn(int рядок);

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

    int document.prevNonSpaceColumn(int рядок, int стовпчик);
    int document.prevNonSpaceColumn(Cursor курсор);

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

    int document.nextNonSpaceColumn(int рядок, int стовпчик);
    int document.nextNonSpaceColumn(Cursor курсор);

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

    int document.prevNonEmptyLine(int рядок);

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

    int document.nextNonEmptyLine(int рядок);

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

    void document.gotoBeginEnv();

  Перейти до початку зовнішнього середовища &latex;.

    void document.gotoEndEnv();

  Перейти до кінця зовнішнього середовища &latex;.

    void document.gotoBeginTexgroup();

  Перейти до початку зовнішньої групи &latex;.

    void document.gotoEndTexgroup();

  Перейти до кінця зовнішньої групи &latex;.

    void document.gotoNextParagraph();

  Перейти до наступного параграфа &latex;.

    void document.gotoPrevParagraph();

  Перейти до попереднього параграфа &latex;.

    void document.gotoNextSectioning();

  Перейти до наступного розділу &latex;.

    void document.gotoPrevSectioning();

  Перейти до попереднього розділу &latex;.

    void document.gotoLine(int рядок);

  Перейти до вказаного `рядка`.

    void document.insertChapter();

  Вставити команду `\chapter` (див. також `document.insertSection()`).

    void document.insertSection();

  Вставити команду `\section`. Подібно до ситуації, коли вибрано пункт меню LaTeX Розділи section, буде відкрито діалогове вікно, за допомогою якого ви зможете вибрати заголовок та мітку для команди початку розділу. Діалогове вікно: вставлення команди початку розділу Діалогове вікно: вставлення команди початку розділу

    void document.insertSubsection();

  Вставити команду `\subsection` (див. також `document.insertSection()`).

    void document.insertSubsubsection();

  Вставити команду `\subsubsection` (див. також `document.insertSection()`).

    void document.insertParagraph();

  Вставити команду `\paragraph` (див. також `document.insertSection()`).

    void document.insertSubparagraph();

  Вставити команду `\subparagraph` (див. також `document.insertSection()`).

    void document.insertLabel();

  Вставити команду `\label`.

    void document.insertReference();

  Вставити команду `\ref`. Подібно до ситуації, коли вибрано пункт меню &latex;Розділи ref, буде відкрито діалогове вікно, за допомогою якого ви зможете вибрати у спадному списку одну з вже встановлених міток. Діалогове вікно: вставляння команди посилання Діалогове вікно: вставляння команди посилання

    void document.insertPageref();

  Вставити команду `\pageref` (див. також `document.insertReference()`).

    void document.insertCitation();

  Вставити команду `\cite`.

    void document.insertIndex();

  Вставити команду `\index`.

    void document.insertFootnote();

  Вставити команду `\footnote`.

    void document.comment();

  Вставити позначку коментування. Позначений фрагмент тексту або поточний рядок буде закоментовано.

    void document.uncomment();

  Зняти позначку коментаря з позначеного фрагмента тексту або поточного рядка.

    void document.uppercase();

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

    void document.lowercase();

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

    void document.capitalize();

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

    void document.joinLines();

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

    void document.insertIntelligentNewline();

  Вставити кмітливий новий рядок (див. ).

    void document.insertIntelligentTabulator();

  Вставити кмітливу табуляцію (див. ).

    void document.editBegin();

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

    void document.editEnd();

  Завершує групу редагування. Останній виклик `editEnd()` (тобто відповідник першого виклику `editBegin()`) завершує крок з редагування.

    StringList document.labelList();

  Повертає всі визначені мітки у форматі `StringList`, який у &javascript; можна використовувати як масив з рядків.

    StringList document.bibitemList();

  Повертає всі визначені пункти списку літератури у форматі `StringList`, який у &javascript; можна використовувати як масив з рядків.

    void document.refreshStructure();

  Оновити дані панелі структури (див. ).

### Програмний інтерфейс &kile;

Для обробки високорівневої взаємодії зі сторонніми чинниками, зокрема вхідними повідомленнями і діалоговими інтерфейсами, використовується загальний об’єкт (змінна) `kile`. Відповідні виклики програмного інтерфейсу поділено на підоб’єкти для структуризації цієї частини програмного інтерфейсу роботи зі скриптами. З точки зору концепції, `kile` чимось подібний до об’єкта `window` у програмному інтерфейсі переглядачів сторінок інтернету.

- `kile.alert`: панелі повідомлень

- `kile.input`: отримати введені користувачем дані

- `kile.wizard`: викликати один з майстрів &kile;

- `kile.script`: отримати дані щодо запущеного скрипту

- `kile.file`: виконати дії над файлами, зокрема читання або запис.

#### Попередження

    void kile.alert.information(String текст, String підпис);

  Показати діалогове вікно Інформація. `текст` — рядок повідомлення, а `підпис` — заголовок вікна повідомлення. Типовим заголовком є назва скрипту.

    void kile.alert.sorry(String текст, String підпис);

  Показати діалогове вікно Вибачте. `текст` — рядок повідомлення, а `підпис` — заголовок вікна повідомлення. Типовим заголовком є назва скрипту.

    void kile.alert.error(String текст, String підпис);

  Показати діалогове вікно Помилка. `текст` — рядок повідомлення, а `підпис` — заголовок вікна повідомлення. Типовим заголовком є назва скрипту.

    String kile.alert.question(String текст, String підпис);

  Показати діалогове вікно Питання. `текст` — рядок повідомлення, а `підпис` — заголовок вікна повідомлення. Типовим заголовком є назва скрипту. Повернутий рядок міститиме `yes` (так) або `no` (ні).

    String kile.alert.warning(String текст, String підпис);

  Показати просте діалогове вікно Попередження. `текст` — рядок повідомлення, а `підпис` — заголовок вікна повідомлення. Типовим заголовком є назва скрипту. Повернутий рядок міститиме `continue` (продовжити) або `cancel` (скасувати).

#### Введення

    String kile.input.getListboxItem(String підпис, String мітка, StringList список);

  Функція, за допомогою якої користувач може вибрати якийсь пункт зі списку у форматі панелі списку варіантів. `підпис` — текст, який буде показано у заголовку, `мітка` — текст, який буде показано як пояснювальний до списку, а `list` — список рядків, які буде вставлено до списку.

    String kile.input.getComboboxItem(String підпис, String мітка, StringList список);

  Функція, за допомогою якої користувач може вибрати якийсь пункт зі спадного списку. `підпис` — текст, який буде показано у заголовку, `мітка` — текст, який буде показано як пояснювальний до списку, а `list` — список рядків, які буде вставлено до списку.

    String kile.input.getText(String підпис, String мітка);

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

    String kile.input.getLatexCommand(String підпис, String мітка);

  Функція, призначена для отримання команди &latex; від користувача. Це означає, що прийматимуться лише латинські літери верхнього і нижнього регістрів. `підпис` — текст, який буде показано на смужці заголовка вікна, а `мітка` — пояснювальний текст до рядка для введення тексту.

    int kile.input.getInteger(String підпис, String мітка, int мінімум = INT_MIN, int максимум = INT_MAX);

  Функція, призначена для отримання цілого числа від користувача. `підпис` — текст, який буде показано на смужці заголовка вікна, а `мітка` — пояснювальний текст до рядка для введення тексту. `мінімум` і `максимум` є найменшим і найбільшим значеннями, які може ввести користувач. Типовими значеннями є `INT_MIN` і `INT_MAX`.

    int kile.input.getPosInteger(String підпис, String мітка, int мінімум = 1, int максимум = INT_MAX);

  Функція, призначена для отримання додатного цілого числа від користувача. `підпис` — текст, який буде показано на смужці заголовка вікна, а `мітка` — пояснювальний текст до рядка для введення тексту. `мінімум` і `максимум` є найменшим і найбільшим значеннями, які може ввести користувач. Типовими значеннями є `1` і `INT_MAX`.

#### Майстер

    void kile.wizard.tabular();

  Викликає Майстер створення таблиць, який допомагає у створенні середовищ tabular (див. ).

    void kile.wizard.array();

  Викликає Майстер створення масивів, який допомагає у створенні середовищ типу array (див. ).

    void kile.wizard.tabbing();

  Викликає Майстер створення табуляцій, який допомагає у створенні середовищ типу tabbing (див. ).

    void kile.wizard.floatEnvironment();

  Викликає Майстер створення плаваючих об’єктів, який допомагає у створенні рухомих елементів набору документа (див. ).

    void kile.wizard.mathEnvironment();

  Викликає Майстер створення формул, який полегшує створення середовищ формул (див. ).

    void kile.wizard.postscript();

  Викликає Майстер інструментів Postscript, який обробку та перевпорядковування документів Postscript (див. ).

#### Скрипт

    String kile.script.name();

  Повертає основу назви запущеного скрипту (без шляху та суфікса назви).

    String kile.script.caption();

  Повертає рядок, яким можна скористатися для створення заголовків вікон попереджень. Виглядає це так: `Script: scriptname.js`.

#### Файл

    Object kile.file.read(String назва_файла);

  Читати вміст текстового файла. Використовується так:

  Приклад: `var res = kile.file.read("шлях/до/файл.txt");`

  Повертає значення `res` як об’єкт (краще сказати, карту) з трьома властивостями:

  - status: дає код стану дії. Можливі значення: 0 (без помилок), 1 (помилка доступу) або 2 (доступ заборонено). Отже, якщо не сталося помилок, значенням `res.status` або `res["status"]` буде 0.

  - result: містить текст відповідного файла.

  - message: містить повідомлення про помилку, якщо така сталася.

    Object kile.file.read();

  Подібний до `read(назва_файла)`, але назву файла вказувати непотрібно. Замість цього, буде відкрито діалогове вікно для вибору файла, дані якого слід прочитати.

    Object kile.file.write(String назва файла, String текст);

  Записати вказаний текст до файла. Має використовуватися так:

  Приклад: `var res = kile.file.write("шлях/до/file.txt","Якийсь фрагмент тексту...");`

  Повернутим значенням `res` є об’єкт (або, краще сказати, карта) з двома властивостями: `status` і `message` (докладніше про властивості див. `read()`).

    Object kile.file.write(String текст);

  Подібний до `write(назва_файла,текст)`, але назва файла не передається. Замість цього відкривається діалогове вікно для вибору назви файла.

    String kile.file.getOpenFileName(String початковийКаталог, String фільтр);

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

  Параметри:

  - початковийКаталог: початковий каталог діалогового вікна відкриття.

  - фільтр: загальний шаблон оболонки або фільтр за типом MIME, який визначає, які файли слід показувати. Дані щодо цього параметра можна знайти у документації з KFileDialog.

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

    String kile.file.getSaveFileName(String початковийКаталог, String фільтр);

  Створює модальний діалог вибору файла і повертає вибрану назву файла або порожній рядок, якщо назву файла не було вибрано. Зауважте, що у разі використання цього методу користувач не повинен обов’язково вибирати назву вже створеного файла. Опис параметрів можна знайти у поясненнях щодо `getOpenFileName()`.

## Приклади

Наведені нижче приклади можуть допомогти вам у ознайомленні зі способами використання програмного інтерфейсу роботи зі скриптами. Ці приклади, а також інші корисні дані можна знайти у каталозі даних &kile;: `KILE_APP_DIR/scripts/`. У кожному скрипті міститься короткий опис його призначення.

### Приклад 1: заміна назви середовища

Замінимо зовнішнє середовище &latex; якимось іншим, зберігаючи розташування курсора. За допомогою нашого скрипту, наприклад, можна буде замінити `\begin{abc}...\end{abc}` на `\begin{xyz}...\end{xyz}`.

    var range = document.environmentRange(false);
    if ( range.isValid() ) {
            var envname = kile.input.getLatexCommand("Введіть назву середовища","Нова назва середовища:");
            if ( envname != '' ) {
                    replaceEnvCommand(envname,range);
            }
    }
    else {
            kile.alert.sorry("Не виявлено зовнішнього середовища LaTeX.");
    }

    function replaceEnvCommand(newEnv,r)
    {
            var c = view.cursorPosition();

            var envname = document.environmentName();

            if ( envname != "" ) {
                    var beginRange = new Range(r.start,new Cursor(r.start.line,r.start.column+8+envname.length));
                    var endRange = new Range(new Cursor(r.end.line,r.end.column-6-envname.length),r.end);

                    document.editBegin();
                    document.replaceText(endRange,"\\end{"+newEnv+"}");
                    document.replaceText(beginRange,"\\begin{"+newEnv+"}");
                    document.editEnd();
            }
    }

### Приклад 2: заміна команди визначення шрифту &latex;

Замінимо зовнішню команду визначення шрифту &latex; якоюсь іншою командою визначення шрифту (курсор має бути розташовано у якійсь групі TeX), зберігаючи розташування курсора. За допомогою нашого скрипту, наприклад, можна буде замінити `\textbf{abc}` на `\textit{abc}`.

    var fontCommands = new Array("\\textbf","\\textit","\\textsl","\\texttt",
                                 "\\textsc","\\textrm","\\textsf","\\emph");

    var range = document.texgroupRange(false);
    if ( range.isValid() ) {
            replaceFontCommand(range);
    }
    else {
            kile.alert.sorry("Не виявлено зовнішньої групи TeX.");
    }

    function replaceFontCommand(r)
    {
            var c = view.cursorPosition();

            document.editBegin();
            view.setCursorPosition(r.start);
            var cmd = document.latexCommand();
            var index = fontCommands.indexOf(cmd);
            if ( index
    >= 0 ) {
                    var cmdRange = document.latexCommandRange();
                    if ( cmdRange.isValid() ) {
                            var newcommand = kile.input.getListboxItem("Вибір",
                                                        "Виберіть команду шрифту:",buildCmdList(cmd));
                            if ( newcommand != "" ) {
                                    document.replaceText(cmdRange,newcommand);
                                    c.column = c.column - (cmd.length - newcommand.length);
                            }
                    }
    /                view.setCursorPosition(c);
            }
            else {
                    kile.alert.sorry("Не виявлено зовнішньої команди визначення шрифту.");
            }
            document.editEnd();
    }

    function buildCmdList(current)
    {
            var result = new Array();
            for ( i=0; i<fontCommands.length; ++i ) {
                    if ( fontCommands[i] != current ) {
                            result.push(fontCommands[i]);
                    }
            }
            return result;
    }

### Приклад 3: створення обгортки позначеного фрагмента тексту

Вмістити позначений фрагмент тексту у параметр команди TeX без зміни розташування курсора. `abc`, наприклад, буде замінено на `\texcommand{abc}`.

    var range = view.selectionRange();

    if ( range.isValid() ) {
            var cmd = kile.input.getLatexCommand("Вибір","Виберіть зовнішню команду LaTeX:");
            if ( cmd != "" ) {
                    surroundTexCommand("\\"+cmd,range);
            }
    }
    else {
            kile.alert.sorry("Нічого не позначено.");
    }

    function surroundTexCommand(cmd,r)
    {
            var c = view.cursorPosition();

            document.editBegin();
            view.clearSelection();
            document.insertText(r.end,"}");
            document.insertText(r.start,cmd+"{");

            c.column = c.column + cmd.length + 2;
            view.setCursorPosition(c);
            document.editEnd();
    }