calibre - en to uk translation catalogue (64 entries)

en: Function mode for Search & replace in the Editor
uk: Функціональний режим для пошуку і заміни у редакторі

en: The :guilabel:`Search & replace` tool in the editor support a *function mode*. In this mode, you can combine regular expressions (see :doc:`regexp`) with arbitrarily powerful Python functions to do all sorts of advanced text processing.
uk: У інструменті пошуку із заміною редактора передбачено підтримку *функціонального режиму*. У цьому режимі ви можете поєднувати формальні вирази (див. :doc:`regexp`) із довільними потужними функціями Python для виконання усіх типів розширеної обробки тексту.

en: In the standard *regexp* mode for search and replace, you specify both a regular expression to search for as well as a template that is used to replace all found matches. In function mode, instead of using a fixed template, you specify an arbitrary function, in the `Python programming language <https://docs.python.org>`_. This allows you to do lots of things that are not possible with simple templates.
uk: У стандартному режимі *формальних виразів* для пошуку з заміною ви вказуєте формальний вираз для пошуку і шаблон, який буде використано для заміни усіх відповідників. У функціональному режимі, замість використання фіксованого шаблона, ви вказуєте довільну функцію, яку написано `мовою програмування Python <https://docs.python.org>`_. Це надає вам змогу виконувати багато завдань, які неможливо виконати за допомогою простих шаблонів.

en: Techniques for using function mode and the syntax will be described by means of examples, showing you how to create functions to perform progressively more complex tasks.
uk: Методики використання функціонального режиму та синтаксис буде описано у форматі прикладів, які продемонструють вам, як створити функції, які виконуватимуть усе більш складні завдання.

en: The Function mode
uk: Режим функцій

en: Automatically fixing the case of headings in the document
uk: Автоматичне виправлення регістру літер у заголовках документа

en: Here, we will leverage one of the builtin functions in the editor to automatically change the case of all text inside heading tags to title case::
uk: Тут ми підсилимо одну із вбудованих функцій редактора, реалізувавши автоматичну заміну регістру символів усього тексту у теґах заголовків на регістр заголовків::

en: For the function, simply choose the :guilabel:`Title-case text (ignore tags)` builtin function. The will change titles that look like: ``<h1>some titLE</h1>`` to ``<h1>Some Title</h1>``. It will work even if there are other HTML tags inside the heading tags.
uk: Для цієї функції просто виберіть вбудовану функцію :guilabel:`Title-case text (ignore tags)`. Ця функція змінює заголовки ось так: з ``<h1>якийсь заГОЛОВОК</h1>`` виходить ``<h1>Якийсь Заголовок</h1>``. Вона працюватиме, навіть якщо у теґах заголовка місяться інші теґи HTML.

en: Your first custom function - smartening hyphens
uk: Ваша перша нетипова функція — кмітливе розставляння дефісів

en: The real power of function mode comes from being able to create your own functions to process text in arbitrary ways. The Smarten Punctuation tool in the editor leaves individual hyphens alone, so you can use the this function to replace them with em-dashes.
uk: Справжня потужність функціонального режиму полягає у можливості створення власних функцій для довільної обробки тексту. Інструмент кмітливої пунктуації у редакторі не чіпає окремих дефісів, отже ви можете скористатися цією функцією для заміни їх на тире.

en: To create a new function, simply click the :guilabel:`Create/edit` button to create a new function and copy the Python code from below.
uk: Щоб створити нову функцію, просто натисніть кнопку :guilabel:`Створити/Редагувати` для створення нової функції і скопіюйте код Python, наведений нижче.

en: Every :guilabel:`Search & replace` custom function must have a unique name and consist of a Python function named replace, that accepts all the arguments shown above. For the moment, we won't worry about all the different arguments to ``replace()`` function. Just focus on the ``match`` argument. It represents a match when running a search and replace. Its full documentation in available `here <https://docs.python.org/library/re.html#match-objects>`_. ``match.group()`` simply returns all the matched text and all we do is replace hyphens in that text with em-dashes, first replacing double hyphens and then single hyphens.
uk: Кожна нетипова функція пошуку з заміною повинна мати неповторну назву і складатися з функції python із назвою replace, яка приймає усі аргументи, вказані вище. Для початку, пропустимо усі різні аргументи функції ``replace()``. Зосередимо нашу увагу на аргументі ``match``. Він представляє відповідник рядка пошуку під час пошуку з заміною. Повну документацію щодо нього можна знайти `тут <https://docs.python.org/library/re.html#match-objects>`_. ``match.group()`` просто повертає увесь відповідний текст, і усе, що нам лишається зробити, це замінити дефіси у цьому тексті на тире. Спочатку замінюємо подвійні дефіси, а потім одинарні.

en: Use this function with the find regular expression::
uk: Скористайтеся цією функцією у формальному виразі пошуку:

en: And it will replace all hyphens with em-dashes, but only in actual text and not inside HTML tag definitions.
uk: І вона замінити усі дефіси на тире, але лише у справжньому тексті, а не у визначеннях теґів HTML.

en: The power of function mode - using a spelling dictionary to fix mis-hyphenated words
uk: Потужність режиму функцій — використання словника для перевірки правопису для виправлення слів із помилковими дефісами

en: Often, e-books created from scans of printed books contain mis-hyphenated words -- words that were split at the end of the line on the printed page. We will write a simple function to automatically find and fix such words.
uk: Часто у електронних книгах, які створено на основі даних оптичного розпізнавання тексту друкованих книг, містяться слова із помилковими переносами — слова, які було розділено дефісом наприкінці рядка друкованої сторінки. Давайте напишемо просту функцію, яка автоматично виявлятиме і виправлятиме такі слова.

en: Use this function with the same find expression as before, namely::
uk: Скористайтеся цією функцією із тим самим виразом для пошуку, що і раніше, а саме::

en: And it will magically fix all mis-hyphenated words in the text of the book. The main trick is to use one of the useful extra arguments to the replace function, ``dictionaries``.  This refers to the dictionaries the editor itself uses to spell check text in the book. What this function does is look for words separated by a hyphen, remove the hyphen and check if the dictionary recognizes the composite word, if it does, the original words are replaced by the hyphen free composite word.
uk: І вона чарівним чином виправить усі слова із помилковими дефісами у тексті книги. Основним трюком тут є використання одного з корисних аргументів функції replace, а саме аргументу ``dictionaries``.  Цей аргумент посилається на словники, які редактор використовує для перевірки правопису тексту книги. Ця функція шукає слова, які відокремлено дефісом, вилучає дефіс і перевіряє, чи розпізнається словником з’єднане слово. Якщо слово розпізнається, початкові слова буде замінено об’єднаним словом без дефіса.

en: Note that one limitation of this technique is it will only work for mono-lingual books, because, by default, ``dictionaries.recognized()`` uses the main language of the book.
uk: Зауважте, що одним із обмежень цієї методики є те, що вона працюватиме лише для одномовних книг, оскільки, типово, ``dictionaries.recognized()`` використовує основну мову книги.

en: Auto numbering sections
uk: Автоматична нумерація розділів

en: Now we will see something a little different. Suppose your HTML file has many sections, each with a heading in an :code:`<h2>` tag that looks like :code:`<h2>Some text</h2>`. You can create a custom function that will automatically number these headings with consecutive section numbers, so that they look like :code:`<h2>1. Some text</h2>`.
uk: Тепер ми розглянемо дещо інший приклад. Припустімо, що у вашому файлі HTML багато розділів, кожен з яких має заголовок у тезі :code:`<h2>`, який виглядає так: :code:`<h2>Якийсь текст</h2>`. Ви можете створити нетипову функцію, яка автоматично нумеруватиме такі заголовки послідовними номерами розділів, щоб виходило ось таке: :code:`<h2>1. Якийсь текст</h2>`.

en: Use it with the find expression::
uk: Скористайтеся цим у виразі для пошуку::

en: Place the cursor at the top of the file and click :guilabel:`Replace all`.
uk: Розташуйте курсор на початку файла і натисніть кнопку :guilabel:`Замінити усі`.

en: This function uses another of the useful extra arguments to ``replace()``: the ``number`` argument. When doing a :guilabel:`Replace All` number is automatically incremented for every successive match.
uk: У цій функції використано ще один з корисних додаткових аргументів ``replace()``: аргумент ``number``. Під час виконання дії :guilabel:`Замінити усе` число автоматично збільшуватиметься для кожного наступного відповідника.

en: Another new feature is the use of ``replace.file_order`` -- setting that to ``'spine'`` means that if this search is run on multiple HTML files, the files are processed in the order in which they appear in the book. See :ref:`file_order_replace_all` for details.
uk: Ще однією новою можливістю є використання ``replace.file_order`` — встановлення значення ``'spine'`` означає, що якщо пошук виконуватиметься для декількох файлів HTML, вони оброблятимуться у порядку, у якому з’являтимуться у тексті книги. Див. :ref:`file_order_replace_all`, щоб дізнатися більше.

en: Auto create a Table of Contents
uk: Автоматичне створення списку змісту

en: Finally, lets try something a little more ambitious. Suppose your book has headings in ``h1`` and ``h2`` tags that look like ``<h1 id="someid">Some Text</h1>``. We will auto-generate an HTML Table of Contents based on these headings. Create the custom function below:
uk: Нарешті, спробуймо щось трохи амбіційніше. Припустімо, що у вашій книзі є заголовки у теґах ``h1`` і ``h2``, які виглядають так: ``<h1 id="якийсь_ідентифікатор">Якийсь Текст</h1>``. Ми автоматично створимо таблицю змісту HTML на основі цих заголовків. Створіть таку нетипову функцію:

en: And use it with the find expression::
uk: І скористайтеся цим у виразі для пошуку::

en: Run the search on :guilabel:`All text files` and at the end of the search, a window will popup with "Debug output from your function" which will have the HTML Table of Contents, ready to be pasted into :file:`toc.html`.
uk: Виконайте пошук у :guilabel:`Всіх текстових файлах`. Наприкінці пошуку буде показано контекстне вікно «Діагностичні повідомлення від вашої функції», у якому буде показано таблицю змісту у форматі HTML, готову до вставлення до :file:`toc.html`.

en: The function above is heavily commented, so it should be easy to follow. The key new feature is the use of another useful extra argument to the ``replace()`` function, the ``data`` object. The ``data`` object is a Python *dictionary* that persists between all successive invocations of ``replace()`` during a single :guilabel:`Replace All` operation.
uk: Наведений вище код функції містить багато коментарів, тому його доволі просто зрозуміти. Ключовою новою можливістю є використання ще одного додаткового аргументу функції ``replace()``, а саме, об’єкта ``data``. Об’єкт ``data`` є *словником* Python, який зберігається протягом усіх послідовних викликів ``replace()`` під час виконання однієї дії :guilabel:`Замінити всі`.

en: Another new feature is the use of ``call_after_last_match`` -- setting that to ``True`` on the ``replace()`` function means that the editor will call ``replace()`` one extra time after all matches have been found. For this extra call, the match object will be ``None``.
uk: Ще однією новою можливістю є використання ``call_after_last_match`` — встановлення для цієї змінної значення ``True`` у функції ``replace()`` означає, що редактор викликатиме ``replace()`` додатковий раз після знайдення усіх відповідників. Для цього додаткового виклику об’єктом-відповідником буде ``None``.

en: This was just a demonstration to show you the power of function mode, if you really needed to generate a Table of Contents from headings in your book, you would be better off using the dedicated Table of Contents tool in :guilabel:`Tools->Table of Contents`.
uk: Тут наведено лише приклади потужності функціонального режиму. Якщо вам дійсно  потрібно створити таблицю змісту на основі заголовків у вашій книзі, вам варто скористатися спеціалізованим інструментом для створення таблиць змісту, а саме, пунктом меню :guilabel:`Інструменти -> Зміст`.

en: The API for the function mode
uk: Програмний інтерфейс функціонального режиму

en: All function mode functions must be Python functions named replace, with the following signature::
uk: Усі функції режиму функцій мають бути функціями Python із назвою replace, з таким підписом::

en: When a find/replace is run, for every match that is found, the ``replace()`` function will be called, it must return the replacement string for that match. If no replacements are to be done, it should return ``match.group()`` which is the original string. The various arguments to the ``replace()`` function are documented below.
uk: Під час виконання дії із пошуку з заміною для кожного знайденого відповідника викликатиметься функція ``replace()`` і має бути повернуто замінений рядок для кожного відповідника. Якщо замін не виконуватиметься, має бути повернуто ``match.group()``, яким є початковий рядок. Документацію з різноманітних аргументів функції ``replace()`` наведено нижче.

en: The ``match`` argument
uk: Аргумент «match»

en: The ``match`` argument represents the currently found match. It is a `Python Match object <https://docs.python.org/library/re.html#match-objects>`_. Its most useful method is ``group()`` which can be used to get the matched text corresponding to individual capture groups in the search regular expression.
uk: Аргумент ``match`` представляє поточний знайдений відповідник. Це `об’єкт Match Python <https://docs.python.org/library/re.html#match-objects>`_. Його найкориснішим методом є ``group()``, метод, яким можна скористатися для отримання відповідного тексту для окремих груп захоплення під час пошуку за формальним виразом.

en: The ``number`` argument
uk: Аргумент «number»

en: The ``number`` argument is the number of the current match. When you run :guilabel:`Replace All`, every successive match will cause ``replace()`` to be called with an increasing number. The first match has number 1.
uk: Аргумент ``number`` є номером поточного відповідника. Коли ви наказуєте програмі :guilabel:`Замінити усе`, виявлення кожного наступного відповідника призводитиме до того, що ``replace()`` викликатиметься зі збільшеним числом. Перший відповідник матиме номер 1.

en: The ``file_name`` argument
uk: Аргумент «file_name»

en: This is the filename of the file in which the current match was found. When searching inside marked text, the ``file_name`` is empty. The ``file_name`` is in canonical form, a path relative to the root of the book, using ``/`` as the path separator.
uk: Це назва файла, у якому було знайдено поточний відповідник. Якщо пошук виконується у позначеному фрагменті тексту, значення ``file_name`` є порожнім. Значення ``file_name`` записується у канонічній формі, як шлях відносно кореневої теки книги. з використанням роздільника елементів шляху ``/``.

en: The ``metadata`` argument
uk: Аргумент «metadata»

en: This represents the metadata of the current book, such as title, authors, language, etc. It is an object of class :class:`calibre.ebooks.metadata.book.base.Metadata`. Useful attributes include, ``title``, ``authors`` (a list of authors) and ``language`` (the language code).
uk: Є метаданими поточної книги, зокрема даними щодо назви, авторів, мови тощо. Є об’єктом класу :class:`calibre.ebooks.metadata.book.base.Metadata`. Серед особливо корисних атрибутів, ``title`` (назва або заголовок книги), ``authors`` (список авторів) та ``language`` (код мови).

en: The ``dictionaries`` argument
uk: Аргумент «dictionaries»

en: This represents the collection of dictionaries used for spell checking the current book. Its most useful method is ``dictionaries.recognized(word)`` which will return ``True`` if the passed in word is recognized by the dictionary for the current book's language.
uk: Збірка словників, які використовуються для перевірки правопису у поточній книзі. Найкориснішим методом є ``dictionaries.recognized(слово)``. Цей метод повертає ``True``, якщо слово пройшло перевірку за словником для мови поточної книги.

en: The ``data`` argument
uk: Аргумент «data»

en: This a simple Python ``dictionary``. When you run :guilabel:`Replace all`, every successive match will cause ``replace()`` to be called with the same ``dictionary`` as data. You can thus use it to store arbitrary data between invocations of ``replace()`` during a :guilabel:`Replace all` operation.
uk: Це простий ``словник`` Python. Після натискання кнопки :guilabel:`Замінити всі` кожен наступний відповідник спричинятиме виклик ``replace()`` із тим самим ``словником`` як даними. Таким чином, ви можете скористатися ним для збереження довільних даних між викликами ``replace()`` під час виконання дії :guilabel:`Замінити всі`.

en: The ``functions`` argument
uk: Аргумент «functions»

en: The ``functions`` argument gives you access to all other user defined functions. This is useful for code re-use. You can define utility functions in one place and re-use them in all your other functions. For example, suppose you create a function name ``My Function`` like this:
uk: Аргумент ``functions`` надає вам доступ до усіх інших визначених користувачем функцій. Корисний для повторного використання коду. Ви можете визначити допоміжні функції у одному місці, а потім скористатися ними у всіх інших ваших функціях. Наприклад, припустімо, що ви створили таку функцію із назвою ``My Function``:

en: Then, in another function, you can access the ``utility()`` function like this:
uk: Далі, у іншій функції, ви можете отримати доступ до функції ``utility()`` ось так:

en: You can also use the functions object to store persistent data, that can be re-used by other functions. For example, you could have one function that when run with :guilabel:`Replace All` collects some data and another function that uses it when it is run afterwards. Consider the following two functions:
uk: Ви також можете скористатися об’єктом ``functions`` для зберігання даних, які може бути повторно використано іншими функціями. Наприклад, ви можете створити функцію, яка під час запуску за допомогою кнопки :guilabel:`Замінити всі` збирає певні дані, і іншу функцію, яка використовує ці зібрані дані під час запуску. Розгляньмо такі дві функції:

en: Debugging your functions
uk: Діагностика ваших функцій

en: You can debug the functions you create by using the standard ``print()`` function from Python. The output of print will be displayed in a popup window after the Find/replace has completed. You saw an example of using ``print()`` to output an entire table of contents above.
uk: Ви можете виконувати діагностику створених вами функцій за допомогою стандартної функції ``print()`` Python. Виведені цією функцією дані буде показано у контекстному вікні після завершення дії з пошуку з заміною. Вище було наведено приклад використання ``print()`` для виведення цілої таблиці змісту.

en: Choose file order when running on multiple HTML files
uk: Вибір порядку файлів під час запуску для обробки декількох файлів HTML

en: When you run a :guilabel:`Replace all` on multiple HTML files, the order in which the files are processes depends on what files you have open for editing. You can force the search to process files in the order in which the appear by setting the ``file_order`` attribute on your function, like this:
uk: Якщо ви виконуєте дію :guilabel:`Замінити всі` для декількох файлів HTML одночасно, порядок, у якому оброблятимуться файли, залежить від того, які з файлів було відкрито для редагування. Ви можете наказати обробляти файли у порядку, у якому вони з’являються у книзі, встановленням атрибута ``file_order`` для вашої функції, ось так:

en: ``file_order`` accepts two values, ``spine`` and ``spine-reverse`` which cause the search to process multiple files in the order they appear in the book, either forwards or backwards, respectively.
uk: ``file_order`` приймає два значення, ``spine`` і ``spine-reverse``, які спричиняють обробку декількох файлів у порядку, у якому вони зустрічаються у книзі, послідовно вниз або вгору списком, відповідно.

en: Having your function called an extra time after the last match is found
uk: Як зробити так, що вашу функцію було викликано ще раз після виявлення останнього відповідника

en: Sometimes, as in the auto generate table of contents example above, it is useful to have your function called an extra time after the last match is found. You can do this by setting the ``call_after_last_match`` attribute on your function, like this:
uk: Іноді, як у прикладі із автоматичним створенням таблиці змісту, який наведено вище, корисно зробити так, щоб вашу функцію було викликано ще раз після виявлення останнього відповідника. Зробити це можна встановленням для вашої функції атрибута ``call_after_last_match``, ось так:

en: Appending the output from the function to marked text
uk: Дописування виведеного функцією до позначеного тексту

en: When running search and replace on marked text, it is sometimes useful to append so text to the end of the marked text. You can do that by setting the ``append_final_output_to_marked`` attribute on your function (note that you also need to set ``call_after_last_match``), like this:
uk: Якщо виконується пошук з заміною для позначеного фрагмента тексту, іноді корисно дописувати текст наприкінці позначеного фрагмента. Зробити це можна встановленням для вашої функції атрибута ``append_final_output_to_marked`` (зауважте, що також слід встановити ``call_after_last_match``), ось так:

en: Suppressing the result dialog when performing searches on marked text
uk: Придушення діалогового вікна результатів під час виконання пошуків у позначеному тексті

en: You can also suppress the result dialog (which can slow down the repeated application of a search/replace on many blocks of text) by setting the ``suppress_result_dialog`` attribute on your function, like this:
uk: Крім того, ви можете придушити появу діалогового вікна результатів (що може уповільнити регулярне застосування пошуку з заміною до багатьох блоків тексту) встановивши для вашої функції атрибут ``suppress_result_dialog``, ось так:

en: More examples
uk: Додаткові приклади

en: More useful examples, contributed by calibre users, can be found in the `calibre E-book editor forum <https://www.mobileread.com/forums/showthread.php?t=237181>`_.
uk: Додаткові корисні приклади, авторами яких є користувачі calibre, можна знайти на `форумі редактора книг calibre <https://www.mobileread.com/forums/showthread.php?t=237181>`_.
