calibre - en to uk translation catalogue (260 entries)

en: The calibre template language
uk: Мова шаблонів calibre

en: The calibre template language is a calibre-specific language used throughout calibre for tasks such as specifying file paths, formatting values, and computing the value for user-specified columns. Examples:
uk: Мова шаблонів calibre є специфічною для calibre мовою програмування, яка використовується у різних компонентах calibre. Її використовують для визначення шляхів до файлів, значення форматування та обчислення значень визначених користувачем стовпчиків. Приклади:

en: Specify the folder structure and file names when saving files from the calibre library to the disk or e-book reader.
uk: Визначення структури каталогів та назви файла при зберіганні файлів з бібліотеки calibre на диск або на пристрій для читання книг.

en: Define rules for adding icons and colors to the calibre book list.
uk: Визначення правил додавання піктограм і кольорів до списку книг calibre.

en: Define `virtual columns` that contain data from other columns.
uk: Визначення «віртуальних» стовпчиків, які містять дані з інших стовпчиків.

en: Advanced library searching.
uk: Розширені можливості пошуку у бібліотеці.

en: Advanced metadata search and replace.
uk: Розширені можливості з пошуку і заміни у метаданих.

en: The language is built around the notion of a `template`, which specifies which book metadata to use, computations on that metadata, and how it is to be formatted.
uk: Мову побудовано навколо поняття «шаблон». Шаблон задає, які метадані книги слід використати, обчислення над цими метаданими, і як їх слід форматувати.

en: Basic templates
uk: Базові шаблони

en: A basic template consists one or more ``template expressions``. A ``template expression`` consists of text and names in curly brackets (``{}``) that is replaced by the corresponding metadata from the book being processed. For example, the default template in calibre used for saving books to device has 4 ``template expressions``::
uk: Базовий шаблон містить один або декілька ``виразів шаблонів``. Вираз шаблона складається з тексту і назв у фігурних дужках (``{}``), які згодом буде замінено на відповідні метадані із оброблюваної книги. Наприклад, типовим шаблоном, який використано для збереження книг на пристроях у calibre, містить 4 ``шаблонних вирази``::

en: For the book "The Foundation" by "Isaac Asimov" the  will become::
uk: Для книги «The Foundation» автора «Isaac Asimov» ми отримаємо::

en: The slashes are not ``template expressions`` because they are not in between ``{}``. Such text is left where it appears. For example, if the template is::
uk: Символи похилих рисок не є ``шаблонними виразами``, оскільки їх немає всередині ``{}``. Такі фрагменти тексту після обробки лишаються на місці. Наприклад, якщо шаблоном є такий::

en: then for "The Foundation" the template produces::
uk: для «The Foundation» шаблон дасть::

en: A ``template expression`` can access all the metadata available in calibre, including custom columns (columns you create yourself), by using a column's ``lookup name``. To find the lookup name for a `column` (sometimes called `fields`), hover your mouse over the column header in calibre's book list. Lookup names for custom columns always begin with ``#``. For series type columns there is an additional field named ``#lookup name_index`` that is the series index for that book in the series. For example, if you have a custom series column named ``#myseries``, there will also be a column named ``#myseries_index``. The standard series column's index is named ``series_index``.
uk: Шаблон може отримувати доступ до усіх метаданих, які доступні у calibre, зокрема нетипових стовпчиків (стовпчиків, які створено користувачем), за їхньою ``назвою для пошуку``. Щоб визначити назву для пошуку для стовпчика (який іноді називають «полем»), наведіть вказівник миші на заголовок стовпчика у списку книг calibre. У назвах для пошуку нетипових стовпчиків першим символом завжди є ``#``. Для стовпчиків типу циклів передбачено додаткове поле із назвою ``'#назва_для_пошуку'_index``, яке містить індекс у циклі. Отже, якщо у вас є нетипове поле циклу із назвою  ``#myseries``, буде також і поле із назвою ``#myseries_index``. Індекс стандартного стовпчика циклу має назву ``series_index``.

en: In addition to the standard column based fields, you also can use:
uk: Окрім полів, заснованих на вмісті стовпчиків, ви також можете використовувати::

en: ``{formats}`` - A list of formats available in the calibre library for a book
uk: ``{formats}`` — список форматів, доступних у бібліотеці calibre для книги

en: ``{identifiers:select(isbn)}`` - The ISBN of the book
uk: ``{identifiers:select(isbn)}`` — ISBN книги

en: If the metadata for the field for a given book is not defined then the field in the template is replaced by the empty string (``''``). For example, consider the following template::
uk: Якщо метаданих поля певної книги не визначено, поле у шаблоні буде замінено на порожній рядок (``''``). Приклад::

en: If Asimov's book "Second Foundation" is in the series "Foundation" then the template produces::
uk: Якщо книга Азімова «Second Foundation» є частиною циклу «Foundation», шаблон дасть::

en: If a series has not been entered for the book then the template produces::
uk: Якщо для книги не введено циклу, шаблон дасть::

en: The template processor automatically removes multiple slashes and leading or trailing spaces.
uk: Обробник шаблонів автоматично вилучає послідовності похилих рисок і початкові та завершальні пробіли.

en: Advanced formatting
uk: Додаткові можливості з форматування

en: In addition to metadata substitution, templates can conditionally include additional text and control how substituted data is formatted.
uk: За допомогою шаблонів, окрім вставляння метаданих, можна виконувати набагато ширший спектр дій. Шаблони можуть включати додатковий текст, якщо виконуються певні умови, і керувати тим, як буде форматовано підставлені дані.

en: **Conditionally including text**
uk: **Умовне включення тексту**

en: Sometimes you want text to appear in the output only if a field is not empty. A common case is ``series`` and ``series_index`` where you want either nothing or the two values separated by a hyphen. calibre handles this case using a special ``template expression`` syntax.
uk: Іноді може виникнути потреба у виведенні тексту, лише якщо певне поле є непорожнім Типовим прикладом є ``series`` і ``series_index``. У цьому прикладі нам потрібен буде або порожній рядок або два значення, які відокремлено дефісом. У calibre для обробки подібних випадків передбачено спеціальний синтаксис запису шаблона.

en: For example and using the above Foundation example, assume you want the template to produce `Foundation - 3 - Second Foundation`. This template produces that output:
uk: Наприклад, використовуючи наведений вище приклад із «Foundation», припустімо, вам потрібно, щоб застосування шаблона давало таке: `Foundation - 3 - Second Foundation`. Цей шаблон дає такий результат:

en: However, if a book has no series the template will produce `- - the title`, which is probably not what you want. Generally, people want the result be the title without the extraneous hyphens. You can accomplish this using the following template syntax:
uk: Втім, якщо книга не належить до циклу, шаблон виведе ``- - заголовок`` Ймовірно, це зовсім не те, що потрібно. Здебільшого, бажаним результатом буде просто ``заголовок``, без зайвих дефісів. Для отримання такого результату слід скористатися такою синтаксичною конструкцією шаблонів::

en: ``{field:|prefix_text|suffix_text}``
uk: ``{field:|текст_префікса|текст_суфікса}``

en: This ``template expression`` says that if ``field`` has the value `XXXX` then the result will be `prefix_textXXXXXsuffix_text`. If ``field`` is empty (has no value) then the result will be the empty string (nothing) because the prefix and suffix are ignored. The prefix and suffix can contain blanks.
uk: Цей ``шаблонний вираз`` визначає, що якщо ``field`` має значення `XXXX`, результатом буде `prefix_textXXXXXsuffix_text`. Якщо ``field`` є порожнім (не має значення), результатом буде порожній рядок (нічого), оскільки префікс і суфікс буде проігноровано. Префікс і суфікс можуть містити пробіли.

en: **Do not use subtemplates (`{ ... }`) or functions (see below) in the prefix or the suffix.**
uk: **Не використовуйте підлеглі шаблони (`{ ... }`) або функції (див. нижче) у префіксі або суфіксі.**

en: Using this syntax, we can solve the above no-series problem with the template::
uk: За допомогою цієї синтаксичної конструкції ми можемо розв'язати поставлену вище задачу з шаблоном::

en: The hyphens will be included only if the book has a series index, which it has only if it has a series. Continuing the Foundation example again, the template will produce `Foundation - 1 - Second Foundation`.
uk: Дефіси буде включено, лише якщо для книги визначено індекс у циклі, а таке трапляється, лише якщо метадані містять запис циклу. Продовжуючи приклад із «Foundation», шаблон дасть `Foundation - 1 - Second Foundation`.

en: Notes:
uk: Нотатки:

en: You must include the colon after the ``lookup name`` if you are using a prefix or a suffix.
uk: Вам слід включити двокрапку після назви для пошуку, якщо ви хочете скористатися префіксом або суфіксом.

en: You must either use either no or both ``|`` characters. Using one, as in ``{field:| - }``, is not allowed.
uk: Вам слід або не використовувати символи ``|``, або використовувати обидва символи; користуватися одним з них, як у ``{field:| - }``, не можна.

en: It is OK to provide no text for either the prefix or the suffix, such as in ``{series:|| - }``. The template ``{title:||}`` is the same as ``{title}``.
uk: Можна не вказувати текст для префікса або суфікса, якось так: ``{series:|| - }``. Шаблон ``{title:||}`` є еквівалентним до шаблона ``{title}``.

en: **Formatting**
uk: **Форматування**

en: Suppose you want the ``series_index`` to be formatted as three digits with leading zeros. This does the trick:
uk: Припустімо, вам потрібно переконатися, що ``series_index`` завжди записуватиметься у форматі з трьох цифр із початковими нулями. Ось як цього досягти:

en: ``{series_index:0>3s}`` - Three digits with leading zeros
uk: ``{series_index:0>3s}`` — три цифри із початковими нулями

en: For trailing zeros, use:
uk: Для кінцевих нулів скористайтеся такою конструкцією:

en: ``{series_index:0<3s}`` - Three digits with trailing zeros
uk: ``{series_index:0<3s}`` — три цифрви із завершальними нулями

en: If you use series indices with fractional values, e.g., 1.1, you might want the decimal points to line up. For example, you might want the indices 1 and 2.5 to appear as 01.00 and 02.50 so that they will sort correctly on a device that does lexical sorting. To do this, use:
uk: Якщо ви використовуєте індекси у циклі із проміжними значеннями (наприклад, 11), вам може знадобитися вирівнювання десяткової крапки. Наприклад, бажаним буде запис індексів 1 і 2.5 як 01.00 і 02.50 для належного упорядковування на пристроях із лексичним упорядкуванням. Щоб досягти потрібного результату, скористайтеся таким шаблоном::

en: ``{series_index:0>5.2f}`` - Five characters consisting of two digits with leading zeros, a decimal point, then 2 digits after the decimal point.
uk: ``{series_index:0>5.2f}`` — п'ять символів складаються із двох цифр і початковими нулями, десяткової крапки і 2 цифр після десяткової крапки.

en: If you want only the first two letters of the data, use:
uk: Якщо вам потрібні лише перші дві літери даних, скористайтеся такою конструкцією:

en: ``{author_sort:.2}`` - Only the first two letters of the author sort name
uk: ``{author_sort:.2}`` — лише перші дві літери імені у впорядкованому списку авторів

en: Much of the calibre template language formatting comes from Python. For more details on the syntax of these advanced formatting operations see the `Python documentation <https://docs.python.org/3/library/string.html#formatstrings>`_.
uk: Більша частина форматування мови шаблонів calibre є похідною від Python. Щоб дізнатися більше про синтаксичні конструкції таких дій з форматування, ознайомтеся із `документацією з Python <https://docs.python.org/3/library/string.html#formatstrings>`_.

en: Using templates to define custom columns
uk: Використання шаблонів для визначення нетипових стовпчиків

en: Templates can be used to display information that isn't in calibre metadata, or to display metadata differently from calibre's normal format. For example, you might want to show the ``ISBN``, a field that calibre does not display. You can accomplish this creating a custom column with the type `Column built from other columns` (hereafter called `composite columns`) and providing a template to generate the displayed text. The column will display the result of evaluating the template. For example, to display the ISBN, create the column and enter ``{identifiers:select(isbn)}`` in the template box. To display a column containing the values of two series custom columns, separated by a comma, use ``{#series1:||,}{#series2}``.
uk: Шаблони використовують для показу даних, яких немає у метаданих calibre або показу даних у форматуванні, яке відрізняється від стандартного форматування calibre. Наприклад, у вас може виникнути потреба бачити ISBN, поле, вміст якого calibre не показує. Для показу таких даних ви можете скористатися нетиповими стовпчиками. Створіть стовпчик із типом «Стовпчик, створений на основі інших стовпчиків» (надалі ми такі стовпчики називатимемо складеними) і введіть до нього шаблон. Результат: calibre показуватиме у стовпчику результат обчислення шаблона. Для показу ISBN створіть стовпчик і введіть ``{identifiers:select(isbn)}`` у поле шаблона. Щоб створити стовпчик, який міститиме значення двох нетипових стовпчиків циклів, скористайтеся шаблоном ``{#series1:||,}{#series2}``.

en: Composite columns can use any template option, including formatting.
uk: Складені стовпчики можуть використовувати будь-які варіанти шаблонів, включно з форматуванням.

en: Note: You cannot edit the data displayed in a composite column. Instead you edit the source columns. If you edit a composite column, for example by double-clicking it, calibre will open the template for editing, not the underlying data.
uk: Зауваження: редагувати дані, які показано у складеному стовпчику не можна. Редагувати слід дані у стовпчиках-джерелах. Якщо ви спробуєте виконати редагування складеного стовпчика, наприклад, подвійним клацанням на даних у ньому, calibre відкриє для редагування шаблон, а не дані, які він виводить.

en: Templates and plugboards
uk: Шаблони і набори метаданих

en: Plugboards are used for changing the metadata written into books during send-to-device and save-to-disk operations. A plugboard permits you to specify a template to provide the data to write into the book's metadata. You can use plugboards to modify the following fields: authors, author_sort, language, publisher, tags, title, title_sort. This feature helps people who want to use different metadata in books on devices to solve sorting or display issues.
uk: Набори метаданих використовуються для внесення змін до метаданих, що записуються до книг під час дій із надсилання на пристрій і збереження на диск. Набір метаданих надає вам змогу вказати шаблон для надання даних, які слід записати до метаданих книги. Ви можете скористатися наборами метаданих для внесення змін до таких полів: authors, author_sort, language, publisher, tags, title, title_sort. Набори метаданих допомагають у використанні спеціалізованих метаданих для книг на пристрої з метою усування проблем із упорядковуванням книг або їхнім показом.

en: When you create a plugboard, you specify the format and device for which the plugboard is to be used. A special device is provided, ``save_to_disk``, that is used when saving formats (as opposed to sending them to a device). Once you have chosen the format and device, you choose the metadata fields to change, providing templates to supply the new values. These templates are `connected` to their destination fields, hence the name `plugboards`. You can of course use composite columns in these templates.
uk: Під час створення набору метаданих ви визначаєте формат і пристрій, для яких використовуватиметься набір. Передбачено особливий пристрій, ``save_to_disk``, який використовується для збереження книг у певних форматах (на відміну від надсилання книг на пристрій). Після вибору формату і пристрою вам слід вибрати поля метаданих для внесення змін і надати шаблони для визначення нових значень цих полів. Ці шаблони буде `з’єднано` з відповідними полями призначення. Ви, звичайно ж, можете використовувати у шаблонах наборів метаданих складені стовпчики.

en: Plugboards are quite flexible and can be written in Single Function Mode, Template Program Mode, General Program Mode, or Python Template mode.
uk: Набори метаданих є доволі гнучкими — їх можна писати у режимі однієї функції, режимі програмування шаблонів, загальному режимі програмування та режимі шаблонів Python.

en: When a plugboard might apply (Content server, save to disk, or send to device), calibre searches the defined plugboards to choose the correct one for the given format and device. For example, to find the appropriate plugboard for an EPUB book being sent to an ANDROID device, calibre searches the plugboards using the following search order:
uk: Якщо до метаданих може бути застосовано набір (на сервері даних, для збереження на диск або надсилання на пристрій), calibre шукає визначені набори метаданих і вибирає належний для заданого формату і пристрою. Наприклад, для того, щоб знайти належний набір метаданих для книги EPUB, яку надсилають на пристрій під керуванням ANDROID, calibre шукає набори метаданих у такому порядку:

en: a plugboard with an exact match on format and device, e.g., ``EPUB`` and ``ANDROID``
uk: набір метаданих із точною відповідністю за форматом і пристроєм, наприклад ``EPUB`` і ``ANDROID``

en: a plugboard with an exact match on format and the special ``any device`` choice, e.g., ``EPUB`` and ``any device``
uk: набір метаданих із точним відповідником за форматом і спеціальним варіантом ``any device``, наприклад ``EPUB`` і ``any device``

en: a plugboard with the special ``any format`` choice and an exact match on device, e.g., ``any format`` and ``ANDROID``
uk: набір метаданих із спеціальним варіантом ``any format`` і точною відповідністю за пристроєм, наприклад ``any format`` і ``ANDROID``

en: a plugboard with ``any format`` and ``any device``
uk: набір метаданих ``any format`` і ``any device``

en: The tags and authors fields have special treatment, because both of these fields can hold more than one item. A book can have many tags and many authors. When you specify that one of these two fields is to be changed, the template's result is examined to see if more than one item is there. For tags, the result is cut apart wherever calibre finds a comma. For example, if the template produces the value ``Thriller, Horror``, then the result will be two tags, ``Thriller`` and ``Horror``. There is no way to put a comma in the middle of a tag.
uk: Поля міток (`tags`) і авторів (`authors`) обробляються у особливий спосіб, оскільки у обох цих полях може міститися декілька записів. У книги може бути багато міток і багато авторів. Якщо ви визначаєте одне з цих двох полів як таке, вміст якого слід змінити, результати використання шаблона буде перевірено на наявність декількох записів. Для міток результат буде розділено на записи за знайденими calibre комами. Наприклад, якщо шаблон створює значення ``Трилер, Жахи``, результатом буде дві мітки, ``Трилер`` і ``Жахи``. Способів додавання коми у окрему мітку не передбачено.

en: The same thing happens for authors, but using a different character for the cut, a `&` (ampersand) instead of a comma. For example, if the template produces the value ``Blogs, Joe&Posts, Susan``, then the book will end up with two authors, ``Blogs, Joe`` and ``Posts, Susan``. If the template produces the value ``Blogs, Joe;Posts, Susan``, then the book will have one author with a rather strange name.
uk: Те саме стосується авторів, але для поділу на записи використовується інший символ, `&` (амперсанд), а не кома. Наприклад, якщо шаблоном створюється значення ``Blogs, Joe&Posts, Susan``, для книги буде визначено двоє авторів, ``Blogs, Joe`` і ``Posts, Susan``. Якщо ж шаблон створює значення ``Blogs, Joe;Posts, Susan``, книга матиме один запис автора із доволі чудернацьким іменем.

en: Plugboards affect the metadata written into the book when it is saved to disk or written to the device. Plugboards do not affect the metadata used by ``save to disk`` and ``send to device`` to create the file names. Instead, file names are constructed using the templates entered on the appropriate preferences window.
uk: Набори метаданих впливають на метадані, які записуються до книги, коли її зберігають на диск або записують на пристрій для читання. Набори метаданих не змінюють метадані, які використовуються діями ``зберегти на диск`` та ``надіслати на пристрій`` для створення назв файлів. Назви файлів будуються за допомогою шаблонів, які вказано у відповідних місцях вікна налаштувань.

en: Using functions in templates - Single Function Mode
uk: Використання функцій у шаблонах — режим єдиної функції

en: Suppose you want to display the value of a field in upper case when that field is normally in title case. You can do this using `template functions`. For example, to display the title in upper case use the ``uppercase`` function, as in ``{title:uppercase()}``. To display it in title case, use ``{title:titlecase()}``.
uk: Припустімо, вам потрібно показати значення поля літерами верхнього регістру, хоча зазвичай вміст цього поля записується регістром символів як у заголовку. Досягти цього можна за допомогою `функцій шаблонів`. Наприклад, для переведення літер у верхній регістр можна скористатися функцією ``uppercase``, ось так: ``{title:uppercase()}``. Для показу назви у форматі, типовому для заголовків, скористайтеся шаблоном ``{title:titlecase()}``.

en: Functions go into the format part of the template, after the ``:`` and before the first ``|`` or the closing ``}`` if no prefix/suffix is used. If you have both a format and a function reference, the function comes after a second ``:``.  Functions return the value of the column specified in the template, suitably modified.
uk: Функції вставляють у частину форматування шаблона Їх вписують після ``:`` і перед першим ``|`` або завершальним ``}``, якщо не використано префікса або суфікса. Якщо вам потрібне одразу форматування і функції, функцію включають після ще одного ``:``. Функції повертають значення стовпчика, вказаного у шаблоні, належним чином зміненим.

en: The syntax for using functions is one of::
uk: Синтаксична конструкція для використання функцій є однією з таких:

en: Function names must always be followed by opening and closing parentheses. Some functions require extra values (arguments), and these go inside the parentheses. Arguments are separated by commas. Literal commas (commas as text, not argument separators) must be preceded by a backslash (``\``) . The last (or only) argument cannot contain a textual closing parenthesis.
uk: За назвами функцій завжди мають іти початкова і завершальна круглі дужки. Деяким функціям обов'язково слід передавати додаткові значення (аргументи), і ці аргументи слід вказувати у дужках. Аргументи відокремлюють комами. Самі коми (коми як текст, а не роздільник аргументів) слід екранувати символом зворотної похилої риски (``\``) . Останній (або єдиний) аргумент не може містити текстової завершальної дужки.

en: Functions are evaluated before format specifications and the prefix/suffix. See further down for an example of using both a format and a function.
uk: Функції обчислюють до специфікацій форматів та префіксів/суфіксів. Нижче наведено приклад одночасного використання форматування та функції.

en: **Important**: If you have programming experience, please note that the syntax in `Single Function Mode` is not what you expect. Strings are not quoted and spaces are significant. All arguments are considered to be constants; there are no expressions.
uk: **Важливе зауваження**: якщо ви маєте досвід програмування, будь ласка, зауважте, що синтаксис у цьому режимі (режимі єдиної функції) не зовсім такий, як ви очікуєте Для рядків не потрібні лапки. Пробіли мають значення. Усі аргументи мають бути сталим; проміжних обчислень не передбачено.

en: **Do not use subtemplates (`{ ... }`) as function arguments.** Instead, use :ref:`Template Program Mode <template_mode>` and :ref:`General Program Mode <general_mode>`.
uk: **Не використовуйте підлеглих шаблонів (`{ ... }`) у аргументах функцій.** Замість них, використовуйте :ref:`режим шаблонного програмування <template_mode>` та :ref:`загальний режим програмування <general_mode>`.

en: Notes on calling functions in Single Function Mode:
uk: Зауваження щодо виклику функцій у режимі єдиної функції:

en: When functions are used in Single Function Mode, the first parameter, ``value``, is automatically replaced by the content of the field specified in the template. For example, when the template ``{title:capitalize()}`` is processed, the content of the ``title`` field is passed as the parameter ``value`` to the capitalize function.
uk: При використанні функцій у режимі єдиної функції перший параметр, ``значення``, буде автоматично замінено на вміст поля, яке вказано у шаблоні. Наприклад, при обробці шаблона ``{title:capitalize()}`` вміст поля ``title`` буде передано як параметр ``значення`` функції capitalize.

en: In the function documentation, the notation ``[something]*`` means that ``something`` can be repeated zero or more times. The notation ``[something]+`` means that the ``something`` is repeated one or more times (must exist at least one time).
uk: У наведеній документації щодо функцій позначення ``[щось]*`` означає, що ``щось`` може бути повторено нуль або більшу кількість разів. Позначення ``[щось]+`` означає, що `щось` повторюється один або декілька разів (але має бути принаймні один такий запис).

en: Some functions use regular expressions. In the template language regular expression matching is case-insensitive.
uk: У деяких функціях використовуються формальні вирази. У мові шаблонів при встановленні відповідності формальних виразів регістр символів не береться до уваги.

en: Functions are documented in :ref:`template_functions_reference`. The documentation tells you what arguments the functions require and what the functions do. For example, here is the documentation of the :ref:`ff_ifempty` function.
uk: Документацію до функцій наведено у розділі :ref:`template_functions_reference`. У документації описано потрібні для роботи функцій аргументи та завдання, які виконують функції. Наприклад, ось документація до функції :ref:`ff_ifempty`.

en: You see that the function requires two arguments, ``value`` and ``text_if_empty``. However, because we are using Single Function Mode, we omit the ``value`` argument, passing only ``text_if_empty``. For example, this template::
uk: Як бачите, функція потребує двох аргументів, ``value`` і ``text_if_empty``. Втім, оскільки ми використовуємо режим єдиної функції, ми пропускаємо аргумент ``value``, передаючи лише ``text_if_empty``. Наприклад, цей шаблон:

en: shows the tags for a book, if any. If it has no tags then it show `No tags on this book`.
uk: показує мітки книги, якщо такі є. Якщо міток немає, показує `No tags on this book`.

en: The following functions are usable in Single Function Mode because their first parameter is ``value``.
uk: Наведені нижче функції можна використовувати у режимі єдиної функції, оскільки їхнім першим параметром є ``значення``.

en: **Using functions and formatting in the same template**
uk: **Використання функцій і форматування у одному шаблоні**

en: Suppose you have an integer custom column ``#myint`` that you want displayed with leading zeros, as in ``003``. One way to do this is to use a format of ``0>3s``. However, by default if a number (integer or float) equals zero then the value is displayed as the empty string so zero values will produce the empty string, not ``000``. If you want to see ``000`` values then you use both the format string and the ``ifempty`` function to change the empty value back to a zero. The template would be::
uk: Припустімо, у нас є нетиповий стовпчик із назвою ``#myint``, у якому містяться цілі числа. Вам потрібно представити їх у форматі із початковими нулями, ось так: ``003``. Для цього можна було б скористатися форматуванням ``0>3s``. Втім, типово, якщо число (ціле або дійсне) дорівнює нулеві, значення буде показано як порожній рядок. Отже, нульові значення початкові значення призводитимуть до порожніх рядків, а не до записів ``000``. Якщо вам потрібні саме значення ``000``, вам слід скористатися одразу і рядком форматування, і функцією ``ifempty`` для заміни порожнього значення на нульове. Шаблон може бути таким::

en: Note that you can use the prefix and suffix as well. If you want the number to appear as ``[003]`` or ``[000]``, then use the template::
uk: Зауважте, що ви можете також використовувати префікс і суфікс. Якщо ви хочете, щоб число було показано як ``[003]`` або ``[000]``, скористайтеся таким шаблоном::

en: General Program Mode
uk: Загальний режим програмування

en: `General Program Mode` (`GPM`) replaces `template expressions` with a program written in the `template language`. The syntax of the language is defined by the following grammar::
uk: `Загальний режим програмування замінює `вирази шаблонів` програмою, яку написано `мовою шаблонів`. Синтаксис мови визначено такою граматикою::

en: a ``top_expression`` always has a value. The value of an ``expression_list`` is the value of the last ``top_expression`` in the list. For example, the value of the expression list ``1;2;'foobar';3`` is ``3``.
uk: ``top_expression`` завжди має значення. Значення ``expression_list`` є значенням останнього ``top_expression`` у списку. Наприклад, значення списку виразів ``1;2;'foobar';3`` дорівнює ``3``.

en: In a logical context, any non-empty value is ``True``
uk: У логічному контексті будь-яке непорожнє значення дорівнює ``True``

en: In a logical context, the empty value is ``False``
uk: У логічному контексті порожнє значення дорівнює ``False``

en: Strings and numbers can be used interchangeably. For example, ``10`` and ``'10'`` are the same thing.
uk: Рядки і числа можна використовувати на рівних правах. Наприклад, ``10`` і ``'10'`` є тим самим значенням.

en: Comments are lines starting with a '#' character, possibly preceded by blanks or tabs.
uk: Коментарями вважаються усі рядки, на початку яких є символ «#», перед яким може бути додано пробіли або табуляції.

en: **Operator precedence**
uk: **Пріоритетність операторів**

en: The operator precedence (order of evaluation) from highest (evaluated first) to lowest (evaluated last) is:
uk: Пріоритетність операторів (порядок обчислення), від найвищої (обчислюються першими) до найнижчої (обчислюються останніми):

en: Function calls, constants, parenthesized expressions, statement expressions, assignment expressions, field references.
uk: Виклики функцій, сталі, вирази у дужках, вирази інструкцій, вирази надання значення, посилання на поля.

en: Unary plus (``+``) and minus (``-``). These operators evaluate right to left.
uk: Унарні плюс (``+``) і мінус (``-``). Обчислення для цих операторів виконується справа ліворуч.

en: These and all the other arithmetic operators return integers if the expression results in a fractional part equal to zero. For example, if an expression returns ``3.0`` it is changed to ``3``.
uk: Ці і усі інші арифметичні операції повертають цілі числа, якщо обчислення виразу призводить до числа із дробовою частиною, яка рівна нулеві. Приклад: якщо результатом обчислення виразу є ``3.0``, його буде замінено на ``3``.

en: Multiply (``*``) and divide (``/``). These operators are associative and evaluate left to right. Use parentheses if you want to change the order of evaluation.
uk: Множення (``*``) і ділення (``/``). Ці дії є асоціативними і обчислюються зліва праворуч. Скористайтеся дужками, якщо ви хочете змінити порядок обчислення.

en: Add (``+``) and subtract (``-``). These operators are associative and evaluate left to right.
uk: Додавання (``+``) і віднімання (``-``). Ці дії є асоціативними, обчислення виконується зліва праворуч.

en: Numeric and string comparisons. These operators return ``'1'`` if the comparison succeeds, otherwise the empty string (``''``). Comparisons are not associative: ``a < b < c`` is a syntax error.
uk: Порівняння чисел і рядків. Ці оператори повертають ``'1'``, якщо порівняння справджується, інакше повертають порожній рядок (``''``). Порівняння не є асоціативними: ``a < b < c`` — синтаксична помилка.

en: String concatenation (``&``). The ``&`` operator returns a string formed by concatenating the left-hand and right-hand expressions. Example: ``'aaa' & 'bbb'`` returns ``'aaabbb'``. The operator is associative and evaluates left to right.
uk: Поєднання рядків (``&``). Оператор ``&`` повертає рядок, який сформовано об'єднанням виразів ліворуч і праворуч від нього. Приклад: ``'aaa' & 'bbb'`` повертає ``'aaabbb'``. Оператор є асоціативним і обчислюється зліва праворуч.

en: Unary logical not (``!``). This operator returns ``'1'`` if the expression is False (evaluates to the empty string), otherwise ``''``.
uk: Унарне логічне заперечення (``!``). Цей оператор повертає ``'1'``, якщо вираз не є істинним (є порожнім рядком), інакше повертає ``''``.

en: Logical and (``&&``). This operator returns '1' if both the left-hand and right-hand expressions are True, or the empty string ``''`` if either is False. It is associative, evaluates left to right, and does `short-circuiting <https://chortle.ccsu.edu/java5/Notes/chap40/ch40_2.html>`_.
uk: Логічне «І» (``&&``). Цей оператор повертає '1', якщо вирази ліворуч і праворуч від нього є істинними, або порожній рядок ``''``, якщо хоча б одне з тверджень ліворуч і праворуч є хибним. Оператор є асоціативним, обчислюється зліва праворуч, і має властивість `скороченого обчислення <https://chortle.ccsu.edu/java5/Notes/chap40/ch40_2.html>`_.

en: Logical or (``||``). This operator returns ``'1'`` if either the left-hand or right-hand expression is True, or ``''`` if both are False. It is associative, evaluates left to right, and does `short-circuiting <https://chortle.ccsu.edu/java5/Notes/chap40/ch40_2.html>`_. It is an `inclusive or`, returning ``'1'`` if both the left- and right-hand expressions are True.
uk: Логічне «АБО» (``||``) Цей оператор повертає ``'1'``, якщо твердження ліворуч або праворуч від нього є істинним, або ``''``, якщо обидва твердження є хибними. Є асоціативним, обчислюється зліва праворуч і має властивість `скороченого обчислення <https://chortle.ccsu.edu/java5/Notes/chap40/ch40_2.html>`_. Оператор є інклюзивним «АБО», тобто повертає ``'1'``, якщо вирази праворуч і ліворуч від нього є істинними.

en: **Field references**
uk: **Посилання на поля**

en: A ``field_reference`` evaluates to the value of the metadata field named by lookup name that follows the ``$`` or ``$$``. Using ``$`` is equivalent to using the :ref:`ff_field` function. Using ``$$`` is equivalent to using the :ref:`ff_raw_field` function. Examples::
uk: Інструкцію ``field_reference`` буде замінено значенням поля метаданих, яке має назву пошуку, яку вказано після ``$`` або ``$$``. Використання ``$`` є еквівалентне до використання функції ref:`ff_field`. Використання ``$$`` є еквівалентним до використання функції :ref:`ff_raw_field`. Приклади::

en: **If expressions**
uk: **Вирази if**

en: ``If`` expressions first evaluate the ``condition``. If the ``condition`` is True (a non-empty value) then the ``expression_list`` in the ``then`` clause is evaluated. If it is False then if present the ``expression_list`` in the ``elif`` or ``else`` clause is evaluated. The ``elif`` and ``else`` parts are optional. The words ``if``, ``then``, ``elif``, ``else``, and ``fi`` are reserved; you cannot use them as identifier names. You can put newlines and white space wherever they make sense. The ``condition`` is a ``top_expression`` not an ``expression_list``; semicolons are not allowed. The ``expression_lists`` are semicolon-separated sequences of ``top_expressions``. An ``if`` expression returns the result of the last ``top_expression`` in the evaluated ``expression_list``, or the empty string if no expression list was evaluated.
uk: У виразах ``if`` спочатку обчислюється ``умова``. Якщо ``умова`` справджується (обчислення дають непорожнє значення), обчислюється ``expression_list`` у інструкції ``then````. Якщо умова не справджується, обчислюється, якщо є, ``expression_list`` у інструкції ``elif`` або ``else``, якщо існують такі інструкції. Частини ``elif`` і ``else`` є необов'язковими. Слова ``if``, ``then``, ``elif``, ``else`` і ``fi`` є зарезервованими, ви не можете використовувати їх як назви ідентифікаторів. Ви можете вставляти розриви рядків та пробіли там, де захочете. Запис ``condition`` є ``top_expression``, а не ``expression_list``; не можна використовувати крапку з комою. Набори ``expression_lists`` є розділеними крапками з комами послідовності ``top_expression``. Вираз ``if`` повертає результат останнього ``top_expression`` у обчисленому ``expression_list`` або порожній рядок, якщо жодного списку виразів не було обчислено.

en: Examples::
uk: Приклади::

en: Nested ``if`` example::
uk: Приклад вкладеного``if``::

en: As said above, an ``if`` produces a value. This means that all the following are equivalent::
uk: Як ми вже згадували вище, ``if`` дає значення. Це означає, що усі вказані нижче інструкції є еквівалентними::

en: For example, this program returns the value of the ``series`` column if the book has a series, otherwise the value of the ``title`` column::
uk: Приклад програми, яка повертає значення у стовпчику ``series``, якщо книга належить до циклу, інакше повертає значення стовпчика ``title``::

en: **For expressions**
uk: **Вирази for**

en: The ``for`` expression iterates over a list of values, processing them one at a time. The ``list_expression`` must evaluate either to a metadata field ``lookup name`` e.g., ``tags`` or ``#genre``, or to a list of values. The :ref:`ff_range` generates a list of numbers. If the result is a valid ``lookup name`` then the field's value is fetched and the separator specified for that field type is used. If the result isn't a valid lookup name then it is assumed to be a list of values. The list is assumed to be separated by commas unless the optional keyword ``separator`` is supplied, in which case the list values must be separated by the result of evaluating the ``separator_expr``. A separator cannot be used if the list is generated by ``range()``. Each value in the list is assigned to the specified variable then the ``expression_list`` is evaluated. You can use ``break`` to jump out of the loop, and ``continue`` to jump to the beginning of the loop for the next iteration.
uk: Вираз ``for`` виконує ітерацію за списком значень, обробляючи їх по одному за раз. Вираз ``list_expression`` має оброблятися до ``назви для пошуку`` поля метаданих, наприклад ``tags`` або ``#genre``, або списку значень. Функція :ref:`ff_range` створює список чисел. Якщо результат є коректною ``назвою для пошуку``, отримується значення поля. Використовується роздільник, вказаний для відповідного типу поля. Якщо результат не є коректною назвою для пошуку, припускається, що це список значень. Припускається, що значення у списку розділено комами, якщо не вказано необов'язкове ключове слово ``separator``. Якщо ключове слово вказано, значення у списку має бути відокремлено результатом обчислення ``separator_expr``. Роздільник не можна використовувати, якщо список створено за допомогою ``range()``. Кожне зі значень у списку надається вказаній змінній, а потім обчислюється ``expression_list``. Ви можете скористатися ``break`` для виходу з циклу і ``continue`` для переходу на початок циклу для наступної ітерації.

en: Example: This template removes the first hierarchical name for each value in Genre (``#genre``), constructing a list with the new names::
uk: Приклад: цей шаблон вилучає першу ієрархічну назву для кожного значення у полі «Жанр» (``#genre``), будуючи список із новими назвами::

en: If the original Genre is `History.Military, Science Fiction.Alternate History, ReadMe` then the template returns `Military, Alternate History, ReadMe`. You could use this template in calibre's :guilabel:`Edit metadata in bulk -> Search & replace` with :guilabel:`Search for` set to ``template`` to strip off the first level of the hierarchy and assign the resulting value to Genre.
uk: Якщо початковим значенням поля «Жанр» було `History.Military, Science Fiction.Alternate History, ReadMe`, шаблон поверне `Military, Alternate History, ReadMe`. Ви можете скористатися цим шаблоном в інструменті calibre :guilabel:`Пакетне редагування метаданих -> Пошук із заміною` ^ у полі :guilabel:`Шукати` слід вказати ``шаблон`` для вилучення першого рівня ієрархії і визначення значення-результату для поля «Жанр».

en: Note: the last line in the template, ``new_tags``, isn't strictly necessary in this case because ``for`` returns the value of the last top_expression in the expression list. The value of an assignment is the value of its expression, so the value of the ``for`` statement is what was assigned to ``new_tags``.
uk: Зауваження: останній рядок у шаблоні, ``new_tags``, у цьому випадку не є строго обов'язковим, оскільки ``for`` повертає значення останнього top_expression у списку виразів. Значенням виразу надання значення є значення виразу, тому значенням інструкції ``for`` є те, що записано до ``new_tags``.

en: **Return stmt**
uk: **Повертає stmt**

en: Return the value of the ``expression``. If executed in a function then it returns the value of the expression to the caller. If executed in the outermost context (the template) then it sets the value of the template to the value of the expression and exits the template.
uk: Повертає значення виразу ``вираз``. Якщо виконано у функції, повертає значення виразу функції виклику. Якщо виконано у зовнішньому контексті (шаблоні), встановлює для значення шаблону значення виразу і виводить з шаблону.

en: **Function definition**
uk: **Визначення функції**

en: If you have repeated code in a template then you can put that code into a local function. The ``def`` keyword starts the definition. It is followed by the function name, the argument list, then the code in the function. The function definition ends with the ``fed`` keyword.
uk: Якщо у вашому шаблоні є код, який слід виконувати декілька разів, ви можете розмістити цей код у локальній функції. Визначення функції слід розпочинати з ключового слова ``def``. Після нього слід вказати назву функції, список аргументів, а потім код функції. Визначення функції завершується ключовим словом ``fed``.

en: Arguments are positional. When a function is called the supplied arguments are matched left to right against the defined parameters, with the value of the argument assigned to the parameter. It is an error to provide more arguments than defined parameters. Parameters can have default values, such as ``a = 25``. If an argument is not supplied for that parameter then the default value is used, otherwise the parameter is set to the empty string.
uk: Аргументи є позиційними. Під час виклику функції надані аргументи заміщують собою зліва праворуч визначені параметри, значення аргументу стає значенням параметра. Надання більшої за кількість визначених параметрів кількості аргументів вважається помилкою. Параметри можуть мати типові значення, наприклад, ``a = 25``. Якщо для параметра не надано аргументу, буде використано типове значення. Якщо такого типового значення немає, буде використано порожній рядок.

en: The ``return`` statement can be used in a local function.
uk: У локальній функції можна скористатися інструкцією ``return``.

en: A function must be defined before it can be used.
uk: Перш ніж функцією можна буде скористатися, її слід визначити.

en: Example: This template computes an approximate duration in years, months, and days from a number of days. The function ``to_plural()`` formats the computed values. Note that the example also uses the ``&`` operator::
uk: Приклад: цей шаблон обчислює приблизну тривалість періоду часу у роках, місяцях та днях на основі кількості днів. Для форматування обчислених значень використано функцію ``to_plural()``. Зауважте, що у прикладі також використано оператор ``&``::

en: **Relational operators**
uk: **Оператори відношень**

en: Relational operators return ``'1'`` if the comparison is true, otherwise the empty string (``''``).
uk: Оператори відношень повертають ``'1'``, якщо порівняння справджується, інакше повертають порожній рядок (``''``).

en: There are two forms of relational operators: string comparisons and numeric comparisons.
uk: Реалізовано дві форми операторів відношень: порівняння рядків і порівняння чисел.

en: String comparisons do case-insensitive string comparison using lexical order. The supported string comparison operators are ``==``, ``!=``, ``<``, ``<=``, ``>``, ``>=``, ``in``, ``inlist``, and ``inlist_field``. For the ``in``, ``inlist``, and ``inlist_field`` operators, the result of the left hand expression is interpreted as a regular expression pattern. They are true if the value of left-hand regular expression matches the value of the right hand expression. The regular expressions are case-insensitive.
uk: Порівняння рядків є порівнянням рядків без врахування регістру символів із використанням лексичного порядку. Підтримуваними операторами порівняння рядків є ``==``, ``!=``, ``<``, ``<=``, ``>``, ``>=``, ``in``, ``inlist`` та ``inlist_field``. Для операторів ``in``, ``inlist`` та ``inlist_field`` результат обчислення лівого операнда вважається формальним виразом взірця. Результатом іхнього обчислення є True, якщо взірець у лівого операнда відповідає значенню правого операнда. Відповідність встановлюється без врахування регістру символів. У формальних виразах враховується регістр символів.

en: The ``inlist`` operator is true if the left hand regular expression matches any one of the items in the right hand list where the items in the list are separated by commas. The ``inlist_field`` operator is true if the left hand regular expression matches any of the items in the field (column) named by the right hand expression, using the separator defined for the field. NB: the ``inlist_field`` operator requires the right hand expression to evaluate to a field name, while the ``inlist`` operator requires the right hand expression to evaluate to a string containing a comma-separated list. Because of this difference, ``inlist_field`` is substantially faster than ``inlist`` because no string conversions or list constructions are done.
uk: Оператор ``inlist`` повертає true, якщо формальний вираз ліворуч від нього відповідає одному із записів у списку праворуч від нього, де записи у списку відокремлено комами. Оператор ``field_inlist`` повертає true, якщо формальний вираз ліворуч від нього відповідає будь-якому зі записів у полі (стовпчику), назву якого вказано праворуч від оператора, з використанням роздільника, який визначено для поля. Зауваження: для використання оператора ``inlist_field`` вираз праворуч від нього має визначати назву поля, а для використання оператора ``inlist`` результ татом обчислення виразу праворуч від нього має бути рядок, що містить відокремлений комами список. Через цю різницю ``inlist_field`` є суттєво швидшим за ``inlist``, оскільки не виконується ніяких перетворень рядків або побудови списків.

en: The numeric comparison operators are ``==#``, ``!=#``, ``<#``, ``<=#``, ``>#``, ``>=#``. The left and right expressions must evaluate to numeric values with two exceptions: both the string value "None" (undefined field) and the empty string evaluate to the value zero.
uk: Операторами числового порівняння є ``==#``, ``!=#``, ``<#``, ``<=#``, ``>#``, ``>=#``. Результатом обчислення лівого і правого операндів мають бути числові значення з двома виключеннями: рядкове значення "None" (невизначене поле) і порожнє значення вважаються рівними нулеві.

en: Examples:
uk: Приклади:

en: ``program: field('series') == 'foo'`` returns ``'1'`` if the book's series is `foo`, otherwise ``''``.
uk: ``program: field('series') == 'foo'`` повертає ``'1'``, якщо циклом книги є `foo`, інакше повертає ``''``.

en: ``program: 'f.o' in field('series')`` returns ``'1'`` if the book's series matches the regular expression ``f.o`` (e.g., `foo`, `Off Onyx`, etc.), otherwise ``''``.
uk: ``program: 'f.o' in field('series')`` повертає ``'1'``, якщо цикл книги відповідає формальному виразу ``f.o`` (наприклад, `foo`, `Off Onyx` тощо), інакше повертає ``''``.

en: ``program: 'science' inlist $#genre`` returns ``'1'`` if any of the values retrieved from the book's genres match the regular expression ``science``, e.g., `Science`, `History of Science`, `Science Fiction` etc., otherwise ``''``.
uk: ``program: 'science' inlist $#genre`` повертає ``'1'``, якщо будь-яке зі значень, отриманих із запису жанрів книги, відповідає формальному виразу ``science``, наприклад, `Science`, `History of Science`, `Science Fiction` тощо. У інших випадках буде повернуто ``''``.

en: ``program: '^science$' inlist $#genre`` returns ``'1'`` if any of the book's genres exactly match the regular expression ``^science$``, e.g., `Science`, otherwise ``''``. The genres `History of Science` and `Science Fiction` don't match.
uk: ``program: '^science$' inlist $#genre`` повертає ``'1'``, якщо будь-який із записів жанрів книги точно відповідає формальному виразу ``^science$``, наприклад, `Science`. Якщо відповідність не буде встановлено, програма поверне ``''``. Жанри `History of Science` і `Science Fiction` вважаються невідповідними.

en: ``program: 'asimov' inlist $authors`` returns ``'1'`` if any author matches the regular expression ``asimov``, e.g., `Asimov, Isaac` or `Isaac Asimov`, otherwise ``''``.
uk: ``program: 'asimov' inlist $authors`` повертає ``'1'``, якщо будь-який із записів авторів відповідає формальному виразу ``asimov``, наприклад, `Asimov, Isaac` або `Isaac Asimov`, якщо таких записів немає, повертає ``''``.

en: ``program: 'asimov' inlist_field 'authors'`` returns ``'1'`` if any author matches the regular expression ``asimov``, e.g., `Asimov, Isaac` or `Isaac Asimov`, otherwise ``''``.
uk: ``program: 'asimov' inlist_field 'authors'`` повертає ``'1'``, якщо будь-який із записів авторів відповідає формальному виразу ``asimov``, наприклад, `Asimov, Isaac` або `Isaac Asimov`, якщо таких записів немає, повертає ``''``.

en: ``program: 'asimov$' inlist_field 'authors'`` returns ``'1'`` if any author matches the regular expression ``asimov$``, e.g., `Isaac Asimov`, otherwise ``''``. It doesn't match `Asimov, Isaac` because of the ``$`` anchor in the regular expression.
uk: ``program: 'asimov$' inlist_field 'authors'`` повертає ``'1'``, якщо будь-який із записів авторів відповідає формальному виразу ``asimov$``, наприклад, `Isaac Asimov`, якщо це не так, повертає ``''``. Не відповідає запису `Asimov, Isaac` через прив'язку ``$`` у формальному виразі.

en: ``program: if field('series') != 'foo' then 'bar' else 'mumble' fi`` returns ``'bar'`` if the book's series is not `foo`. Otherwise it returns ``'mumble'``.
uk: ``program: if field('series') != 'foo' then 'bar' else 'mumble' fi`` повертає ``'bar'``, якщо циклом книги не є `foo`, інакше повертає ``mumble``.

en: ``program: if '^(foo|1632)$' in field('series') then 'yes' else 'no' fi`` returns ``'yes'`` if series is either `foo` or `1632`, otherwise ``'no'``.
uk: ``program: if '^(foo|'1632)$' in field('series') then 'yes' else 'no' fi`` повертає ``'yes'``, якщо циклом є `foo` або `1632`, інакше повертає ``'no'``.

en: ``program: if 11 > 2 then 'yes' else 'no' fi`` returns ``'no'`` because the ``>`` operator does a lexical comparison.
uk: ``program: if 11 > 2 then 'yes' else 'no' fi`` повертає ``'no'``, оскільки оператор ``>`` виконує лексичне порівняння.

en: ``program: if 11 ># 2 then 'yes' else 'no' fi`` returns ``'yes'`` because the ``>#`` operator does a numeric comparison.
uk: ``program: if 11 > 2 then 'yes' else 'no' fi`` повертає ``'yes'``, оскільки оператор ``>#`` виконує числове порівняння.

en: **Functions in General Program Mode**
uk: **Функції у режимі загального програмування**

en: See :ref:`template_functions_reference` for the list of functions built into the template language.
uk: Див. розділ :ref:`template_functions_reference`, у якому наведено список функцій, які вбудовано до мови шаблонів.

en: As opposed to :ref:`Single Function Mode <single_mode>`, in General Program Mode you must specify the first parameter ``value``.
uk: На відміну від :ref:`режиму єдиної функції <single_mode>`, у режимі загального програмування вам доведеться вказувати перший параметр, ``value``.

en: All parameters are expression_lists (see the grammar above).
uk: Усі параметри є expression_lists (див. граматику вище).

en: More complex programs in template expressions - Template Program Mode
uk: Складніші програми у виразах шаблонів — режим програмування шаблонів.

en: `Template Program Mode` (`TPM`) is a blend of :ref:`General Program Mode <general_mode>` and :ref:`Single Function Mode <single_mode>`. `TPM` differs from Single Function Mode in that it permits writing template expressions that refer to other metadata fields, use nested functions, modify variables, and do arithmetic. It differs from `General Program Mode` in that the template is contained between ``{`` and ``}`` characters and doesn't begin with the word ``program:``. The program portion of the template is a General Program Mode expression list.
uk: `Режим програмування шаблонів` є сумішшю :ref:`загального режиму програмування <general_mode>` і :ref:`режиму єдиної функції <single_mode>`. Режим програмування шаблонів відрізняється від режиму єдиної функції тим, що у ньому можна писати вирази шаблонів, які посилаються на інші поля метаданих, використовувати вкладені функції, змінювати значення змінних і виконувати арифметичні дії. Він відрізняється від загального режиму програмування тим, що шаблон міститься між символами ``{`` і ``}`` і не починається зі слова ``program:``. Програмна частина шаблона є списком виразів загального режиму програмування.

en: Example: assume you want a template to show the series for a book if it has one, otherwise show the value of a custom field #genre. You cannot do this in the :ref:`Single Function Mode <single_mode>` because you cannot make reference to another metadata field within a template expression. In `TPM` you can, as the following expression demonstrates::
uk: Почнімо з прикладу. Припустімо, що ви хочете, щоб ваш шаблон показував цикл для книги, яка належить до циклу, і значення нетипового поля #genre, якщо книга не належить до циклів. Зробити це за допомогою :ref:`режиму єдиної функції <single_mode>` неможливо, оскільки ви не можете послатися на інше поле метаданих у виразі шаблона. Але у програмному режимі ви можете це зробити. Спрацює такий вираз::

en: The example shows several things:
uk: Приклад демонструє декілька речей:

en: `TPM` is used if the expression begins with ``:'`` and ends with ``'}``. Anything else is assumed to be in :ref:`Single Function Mode <single_mode>`.
uk: `Режим програмування шаблонів` буде використано, якщо вираз починається з ``:'`` і завершується ``'}``. Усі інші варіанти вважатимуться використанням :ref:`режиму єдиної функції <single_mode>`.

en: If the template contains a prefix and suffix, the expression ends with ``'|`` where the ``|`` is the delimiter for the prefix. Example::
uk: Якщо у шаблоні міститься префікс і суфікс, вираз завершується на ``'|``, де ``|`` — роздільник для префікса. Приклад::

en: Functions must be given all their arguments. For example, the standard built-in functions must be given the initial parameter ``value``.
uk: Функціям мають передаватися усі їхні аргументи. Наприклад, стандартним вбудованим функціями слід передавати початковий параметр ``значення``.

en: The variable ``$`` is usable as the ``value`` argument and stands for the value of the field named in the template, ``series`` in this case.
uk: Змінну ``$`` використовують як аргумент ``значення``, вона замінює значення поля, яке іменовано у шаблоні, у цьому випадку ``series``.

en: white space is ignored and can be used anywhere within the expression.
uk: пробіли буде проігноровано; їх можна використовувати будь-де у виразі.

en: constant strings are enclosed in matching quotes, either ``'`` or ``"``.
uk: сталі рядки слід брати у відповідні лапки ``'`` або ``"``.

en: In `TPM`, using ``{`` and ``}`` characters in string literals can lead to errors or unexpected results because they confuse the template processor. It tries to treat them as template expression boundaries, not characters. In some but not all cases you can replace a ``{`` with ``[[`` and a ``}`` with `]]`. Advice: if your program contains ``{`` and ``}`` characters then you should use `General Program Mode`.
uk: У режимі програмування шаблонів використання символів ``{`` і ``}`` у рядкових літералах режиму програмування шаблонів може призвести до помилок або неочікуваних результатів, оскільки ці символи заважають нормальній роботі обробника шаблонів. Він намагається обробити їх як межі виразу шаблона, а не символи. У деяких, але не в усіх випадках, ви можете замінити ``{`` на ``[[`` і ``}`` на `]]`. Порада: якщо у вашій програмі є символи ``{`` і ``}``, вам слід користуватися `загальним режимом програмування`.

en: Python Template Mode
uk: Режим шаблонів Python

en: Python Template Mode (PTM) lets you write templates using native Python and the `calibre API <https://manual.calibre-ebook.com/develop.html#api-documentation-for-various-parts-of-calibre>`_. The database API will be of most use; further discussion is beyond the scope of this manual. PTM templates are faster and can do more complicated operations but you must know how to write code in Python using the calibre API.
uk: Режим шаблонів Python (PTM) надає вам змогу писати шаблони за допомогою мови Python та `програмного інтерфейсу calibre <https://manual.calibre-ebook.com/develop.html#api-documentation-for-various-parts-of-calibre>`_. Найкориснішим програмним інтерфейсом буде програмний інтерфейс роботи з базою даних. Подальше обговорення не належить до предмета цього підручника. Шаблони PTM є швидшими і можуть виконувати складніші дії, але вам потрібні будуть значення щодо написання коду мовою Python за допомогою програмного інтерфейсу calibre.

en: A PTM template begins with:
uk: Шаблон PTM розпочинається так:

en: You can add the above text to your template using the context menu, usually accessed with a right click. The comments are not significant and can be removed. You must use python indenting.
uk: Ви можете додати наведений вище текст до вашого шаблона за допомогою контекстного меню, доступ до якого можна отримати за допомогою клацання правою кнопкою миші. Коментарі є необов'язковими — їх можна вилучити. Вам слід використовувати відступи, які використовують у Python.

en: The context object supports ``str(context)`` that returns a string of the context's contents, and ``context.attributes`` that returns a list of the attribute names in the context.
uk: Для об'єкта контексту передбачено підтримку ``str(контекст)``, яка повертає рядок вмісту контексту, та ``context.attributes``, який повертає список назв атрибутів у контексті.

en: The ``context.funcs`` attribute allows calling Built-in and User template functions, and Stored GPM/Python templates, so that you can execute them directly in your code. The functions are retrieved using their names. If the name conflicts with a Python keyword, add an underscore to the end of the name. Examples:
uk: За допомогою атрибуту ``context.funcs`` можна викликати вбудовані функції та функції шаблонів користувача, а також збережені шаблони GPM/Python так, щоб їх можна було виконати безпосередньо у вашому коді. Функції буде отримано за назвами. Якщо виникне конфлікт назв із ключовим словом Python, додайте символ підкреслювання наприкінці назви. Приклади:

en: Here is an example of a PTM template that produces a list of all the authors for a series. The list is stored in a `Column built from other columns, behaves like tags`. It shows in :guilabel:`Book details` and has the :guilabel:`on separate lines` checked (in :guilabel:`Preferences->Look & feel->Book details`). That option requires the list to be comma-separated. To satisfy that requirement the template converts commas in author names to semicolons then builds a comma-separated list of authors. The authors are then sorted, which is why the template uses author_sort.
uk: Нижче наведено приклад шаблона PTM, який створює список усіх авторів для циклу книг. Список буде збережено до «стовпчика побудованого на основі інших стовпчиків, який поводитиме себе як мітки». Його буде показано у :guilabel:`Подробицях щодо книги`, для нього буде використано позначений стан пункту :guilabel:`в окремих рядках` (на сторінці :guilabel:`Налаштування->Вигляд та поведінка->Подробиці щодо книги`). Використання цього пункту потребуватиме відокремлення записів у списку комами. Щоб виконати цю вимогу, шаблон перетворить коми у іменах авторів на крапки з комами, а потім побудує список відокремлених комами записів авторів. Записи авторів буде упорядковано, тому у шаблоні використано author_sort.

en: The output in :guilabel:`Book details` looks like this:
uk: Виведені дані на панелі :guilabel:`Подробиці щодо книги` виглядатимуть так:

en: E-book conversion dialog
uk: Вікно перетворення електронних книг

en: Templates and URLs
uk: Шаблони і адреси

en: You can use templates to construct URLs. Two cases are described here:
uk: Ви можете скористатися шаблонами для побудови адрес. Тут описано два випадки:

en: Custom column :guilabel:`Book details` search URLs
uk: Адреси пошуку нетипових стовпчиків :guilabel:`Подробиць щодо книги`

en: The calibre URL scheme
uk: Схема адреси calibre

en: **Custom column book details search URLs**
uk: Адреси пошуку нетипових стовпчиків «Подробиць щодо книги»

en: When you create a custom column you can provide a URL to be used in :guilabel:`Book details` using a template. For example, if you have a custom column for `Translators` you can define a URL to take you to a site for translators. Book details search URLs can be provided for `Text`, `Enumerated`, `Series`, and `Column built from other column` column types.
uk: Коли ви створюєте нетиповий стовпчик ви можете вказати адресу для використання на панелі :guilabel:`Подробиці щодо книги` за допомогою шаблону. Наприклад, якщо у вас є нетиповий стовпчик для параметра «Перекладачі», ви можете визначити адресу, яка спрямовуватиме вас на сайт для перекладачів. Адреси для пошуку подробиць щодо книги можна надати для типів стовпців `Текст`, `Пронумерований`, `Цикл` та `Стовпчик, побудований з інших стовпчиків`.

en: When an item with a `search template` is clicked in :guilabel:`Book details` the template is evaluated. It is provided the normal book metadata. It is also provided three additional fields:
uk: Якщо клацнути на елементі з `шаблоном пошуку` на панелі :guilabel:`Подробиці щодо книги`, шаблон буде оброблено. Йому буде надано звичайні метадані книги. Також передбачено три додаткові поля:

en: ``item_value``: the value of the clicked item.
uk: ``item_value``: значення натиснутого запису.

en: ``item_value_quoted``: the value of clicked item, URL-encoded. Special characters are escaped to make them valid in URLs and spaces are replaced by ``'+'`` (plus) signs.
uk: ``item_value_quoted``: значення натиснутого запису, закодоване як адресу. Спеціальні символи буде екрановано, щоб створити коректну адресу, а пробіли буде замінено символами ``'+'`` (плюс).

en: ``item_value_no_plus``: the value of clicked item, URL-encoded. Special characters are escaped to make them valid in URLs and spaces are replaced by the ``%20``, not plus.
uk: ``item_value_no_plus``: значення натиснутого запису, закодоване як адресу. Спеціальні символи буде екрановано, щоб створити коректну адресу, а пробіли буде замінено ``%20``, а не плюсами.

en: There are several ways to construct the URL. The following use Wikipedia as an example.
uk: Існує декілька способів побудувати адресу. У наступному прикладі використано адреси Вікіпедії.

en: The simplest is a basic template::
uk: Найпростіший базовий шаблон::

en: In some cases you might want to do more processing. There are four template functions you can use, depending on the complexity of the processing.
uk: У деяких випадках вам може знадобитися додаткова обробка. Залежно від складності обробки можна використовувати чотири шаблонні функції.

en: For example, assume you have a custom column `Translators` (``#translators``) where the names are `Last name, First name`. You might need to convert the name to `First name Last name` when creating the URL. You can use the :ref:`ff_make_url` function to do this::
uk: Наприклад, припустімо, що у вас є нетиповий стовпчик `Перекладачі` (``#translators``), де імена записано так: «Прізвище, Ім’я». Під час створення адреси вам може знадобитися перетворити ім’я на `Ім’я Прізвище’. Для цього можна використати функцію :ref:`ff_make_url`::

en: If we assume that the translator's name is `Boy-Żeleński, Tadeusz` then the above template produces the link::
uk: Якщо припускати, що ім'я перекладача `Boy-Żeleński, Tadeusz`, записаний вище шаблон створить таке посилання::

en: Note that the person's first name is now first, the space is now a plus, and that the non-English characters in the last name are URL-encoded.
uk: Зауважте, що ім’я особи тепер є першим, пробіл – плюсом, а неанглійські символи в прізвищі закодовані в адресу.

en: The functions :ref:`ff_make_url_extended`, :ref:`ff_query_string`, and :ref:`ff_encode_for_url` might be useful depending upon any additional processing complexity.
uk: Залежно від складності додаткової обробки, можуть бути корисними функції :ref:`ff_make_url_extended`, :ref:`ff_query_string` і :ref:`ff_encode_for_url`.

en: **The calibre URL scheme**
uk: **Схема адрес calibre**

en: Calibre supports several different URLs to navigate your calibre libraries. This section shows how to use templates to construct some of the URLs. See :doc:`url_scheme` for details on the URLs available.
uk: У Calibre передбачено підтримку декількох різних адрес для навігації бібліотеками calibre. У цьому розділі показано, як використовувати шаблони для створення деяких адрес. Перегляньте :doc:`url_scheme` для отримання докладніших відомостей про доступні адреси.

en: Switch to a specific library. The syntax of this URL is::
uk: Перемкнутися на певну бібліотеку. Синтаксис цієї адреси є таким::

en: ``Library_Name`` must be replaced with the name of the calibre library you wish to open. The library name is shown in the title bar of the window. It is a simple name, not the file path to the library. You must spell it as shown in the title bar, including letter case. The character ``_`` (underscore) stands for the current library. If the name contains any spaces or special characters then it must be hex encoded using the :ref:`ff_to_hex` function, as in the following example::
uk: `Library_Name`` слід замінити назвою бібліотеки calibre, яку ви хочете відкрити. Назву бібліотеки буде показано у рядку заголовка вікна. Це проста назва, а не шлях до бібліотеки. Вам слід написати його так, як показано у рядку заголовка, включаючи регістр літер. Символ ``_`` (підкреслення) позначає поточну бібліотеку. Якщо назва містить пробіли або спеціальні символи, вона має бути закодована у шістнадцятковому форматі за допомогою функції :ref:`ff_to_hex`, як у наступному прикладі:

en: The template generates the URL::
uk: Шаблон створює таку адресу::

en: You can replace the ``current_library_name()`` function with the actual name of the library, as in::
uk: Ви можете замінити функцію ``current_library_name()`` на справжню назву бібліотеки, як-от::

en: Links to show books. These links select a book in the calibre library. The syntax for this URL is::
uk: Посилання для показу книг. Ці посилання позначають книгу у бібліотеці calibre. Синтаксис такої адреси::

en: The ``book id`` is the numeric calibre id for the book, available to templates as ``$id``. As above, the library name might need to be hex encoded. Here is an example::
uk: ``book id`` — це числовий ідентифікатор calibre для книги, доступний для шаблонів як ``$id``. Як і вище, назва бібліотеки може потребувати шістнадцяткового кодування. Ось приклад::

en: It produces the URL::
uk: Створює таку адресу::

en: Searching for books. These links search for books in the specified calibre library. The syntax for this URL is::
uk: Пошук книг. Ці посилання шукають книги у вказаній бібліотеці calibre. Синтаксис такої адреси::

en: where `query` is any valid calibre search expression. You must hex encode any query containing spaces or special characters, which generally means all of them. For example, the calibre search expression for searching for a hierarchical tag beginning with 'AA' is ``tags:"=.AA"``. This template constructs a search URL for that expression::
uk: де `query` — будь-який коректний вираз пошуку calibre. Будь-який запит, що містить пробіли або спеціальні символи, що, як правило, означає їх усі, слід кодувати шістнадцятковими послідовностями. Наприклад, пошуковий вираз calibre для пошуку ієрархічної мітки, що починається з 'AA': ``tags:"=.AA"``. Цей шаблон створює адресу пошуку для цього виразу::

en: The resulting URL is::
uk: Адреса-результат::

en: Here is an example of the same URL built using the :ref:``ff_make_url_extended`` function instead of :ref:`ff_strcat`::
uk: Ось приклад тієї самої адреси, яку побудовано за допомогою функції :ref:``ff_make_url_extended``, замість :ref:`ff_strcat`()::

en: Open a book details window on a book in some library. The syntax for this URL is::
uk: Відкрити панель подробиць щодо книги у певній бібліотеці. Синтаксис цієї адреси::

en: An example template is::
uk: Приклад шаблону::

en: which produces the URL::
uk: який створює адресу::

en: Open the notes associated with an author/series/etc. The syntax of the URL is::
uk: Відкрити нотатки, які пов'язано із автором, циклом тощо. Синтаксис адреси::

en: ``Field_Name`` is the lookup name of the field. If the field is a custom column then replace the ``#`` character with an underscore (``_``). ``Item_Id`` is the internal numeric ID of the value in the field. There isn't a template function that returns the ``Item_Id``, so templates will normally use the second form, ``Hex_Encoded_Item_Name``. Here is a sample template that opens the note for the person ``Boy-Żeleński, Tadeusz`` in the field ``#authtest``::
uk: ``Field_Name`` — це пошукова назва поля. Якщо поле є нетиповим стовпчиком, замініть символ ``#`` на підкреслення (``_``). ``Item_Id`` – це внутрішній числовий ідентифікатор значення у полі. Немає шаблонної функції, яка повертає ``Item_Id``, тому шаблони зазвичай використовують другу форму, ``Hex_Encoded_Item_Name``. Ось зразок шаблону, який відкриває нотатку для особи ``Boy-Żeleński, Tadeusz`` у полі ``#authtest``::

en: Stored templates
uk: Збережені шаблони

en: Both :ref:`General Program Mode <general_mode>` and :ref:`Python Template Mode <python_mode>` support saving templates and calling those templates from another template, much like calling stored functions. You save templates using :guilabel:`Preferences->Advanced->Template functions`. More information is provided in that dialog. You call a template the same way you call a function, passing positional arguments if desired. An argument can be any expression. Examples of calling a template, assuming the stored template is named ``foo``:
uk: У :ref:`загальному режимі програмування <general_mode>` і :ref:`режимі шаблонів Python<python_mode> передбачено можливість збереження шаблонів загального режиму програмування та виклику цих шаблонів з інших шаблонів, подібно до виклику збережених функцій. Зберегти шаблони можна за допомогою пункту :guilabel:`Налаштування->Додатково->Шаблонні функції`. у відповідному діалоговому вікні буде наведено довідкову інформації. Викликати шаблон можна у той самий спосіб, що і функцію, передавши йому, якщо потрібно, позиційні аргументи. Аргументом може бути будь-який вираз. Приклади виклику шаблону, де ми припускаємо, що збережений шаблон має назву ``foo``:

en: ``foo()`` -- call the template passing no arguments.
uk: ``foo()`` — виклик шаблону без передавання аргументів.

en: ``foo(a, b)`` call the template passing the values of the two variables ``a`` and ``b``.
uk: ``foo(a, b)`` — виклик шаблону з передаванням значень двох змінних — ``a`` і ``b``.

en: ``foo(if field('series') then field('series_index') else 0 fi)`` -- if the book has a ``series`` then pass the ``series_index``, otherwise pass the value ``0``.
uk: ``foo(if field('series') then field('series_index') else 0 fi)`` — якщо книга належить до циклу, передати номер книги у циклі, інакше — передати значення ``0``.

en: In GPM you retrieve the arguments passed in the call to the stored template using the ``arguments`` function. It both declares and initializes local variables, effectively parameters. The variables are positional; they get the value of the parameter given in the call in the same position. If the corresponding parameter is not provided in the call then ``arguments`` assigns that variable the provided default value. If there is no default value then the variable is set to the empty string. For example, the following ``arguments`` function declares 2 variables, ``key``, ``alternate``::
uk: Отримання аргументів відбувається за допомогою виклику збереженого шаблона за допомогою функції ``arguments``. Ця функція одразу оголошує і ініціалізує локальні змінні, які виконують роль параметрів. Ці змінні є позиційними — їм надається значення, яке стоїть у виклику на відповідній позиції. Якщо відповідне значення змінної не було надано у виклику, ``arguments`` надає параметру типового значення. Якщо типове значення не вказано, змінній буде надано значення порожнього рядка. Наприклад, наведена нижче функція ``arguments`` оголошує 2 змінні — ``key``, ``alternate``::

en: Examples, again assuming the stored template is named ``foo``:
uk: У наведених нижче прикладах знову припускаємо, що збережений шаблон має назву ``foo``:

en: ``foo('#myseries')`` -- argument ``key`` is assigned the value ``'myseries'`` and the argument ``alternate`` is assigned the default value ``'series'``.
uk: ``foo('#myseries')`` — аргумент ``key`` матиме значення ``'myseries'``, а аргумент ``alternate`` матиме типове значення ``'series'``.

en: ``foo('series', '#genre')`` the variable ``key`` is assigned the value ``'series'`` and the variable ``alternate`` is assigned the value ``'#genre'``.
uk: ``foo('series', '#genre')`` — змінній ``key`` буде надано значення ``'series'``, а змінній ``alternate`` — значення ``'#genre'``.

en: ``foo()`` -- the variable ``key`` is assigned the empty string and the variable ``alternate`` is assigned the value ``'series'``.
uk: ``foo()`` -— змінній ``key`` буде надано значення порожнього рядка, а змінній ``alternate`` — значення ``'series'``.

en: In PTM the arguments are passed in the ``arguments`` parameter, which is a list of strings. There isn't any way to specify default values. You must check the length of the ``arguments`` list to be sure that the number of arguments is what you expect.
uk: У PTM аргументи буде передано у формі параметра ``arguments``, який є списком рядків. Не існує способу вказати типові значення. Вам слід перевірити довжину списку ``arguments``, щоб переконатися, що кількість аргументів є тією, на яку ви сподіваєтеся.

en: An easy way to test stored templates is using the ``Template tester`` dialog. For ease of access give it a keyboard shortcut in :guilabel:`Preferences->Advanced->Keyboard shortcuts->Template tester`. Giving the ``Stored templates`` dialog a shortcut will help switching more rapidly between the tester and editing the stored template's source code.
uk: Простим способом тестування збережених шаблонів є використання вікна ``Засіб тестування шаблонів``. Для полегшення доступу надайте цьому вікну клавіатурного скорочення за допомогою пункту :guilabel:`Налаштування->Додатково->Клавіатурні скорочення->Засіб тестування шаблонів`. Надання клавіатурного скорочення вікну ``Збережені шаблони`` допоможе вам швидше перемикатися між тестуванням та редагування початкового коду збереженого шаблону.

en: Providing additional information to templates
uk: Надання додаткової інформації шаблонам

en: A developer can choose to pass additional information to the template processor, such as application-specific book metadata or information about what the processor is being asked to do. A template can access this information and use it during the evaluation.
uk: Розробник може передати додаткові відомості обробнику шаблонів, зокрема, специфічні для книги метадані або відомості про те, що слід виконати обробнику. Шаблон може отримувати доступ до цих відомостей і використовувати їх під час обробки.

en: **Developer: how to pass additional information**
uk: **Розробник: як передати додаткові відомості**

en: The additional information is a Python dictionary containing pairs ``variable_name: variable_value`` where the values must be strings. The template can access the dictionary, creating template local variables named ``variable_name`` containing the value ``variable_value``. The user cannot change the name so it is best to use names that won't collide with other template local variables, for example by prefixing the name with an underscore.
uk: Додатковими відомостями є словник Python, який містить пари ``назва_змінної: значення_змінної``, де значеннями мають бути рядки. Шаблон може отримувати доступ до словника, створюючи локальні змінні із назвами ``назва_змінної``, які міститимуть значення ``значення_змінної``. Користувач не може змінювати назву, тому краще користуватися назвами, які не збігатимуться із локальними змінними інших шаблонів. Можна, наприклад, додати до усіх назв початковий символ підкреслювання.

en: This dictionary is passed to the template processor (the ``formatter``) using the named parameter ``global_vars=your_dict``. The full method signature is::
uk: Цей словник буде передано обробнику шаблонів (``форматувальнику``) за допомогою іменованого параметра ``global_vars=ваш_словник``. Ось повний запис методу::

en: **Template writer: how to access the additional information**
uk: **Розробник шаблонів: як отримати доступ до додаткових відомостей**

en: You access the additional information (the ``globals`` dictionary) in a template using the template function::
uk: Отримати доступ до додаткових відомостей (словника ``globals``) у шаблоні можна за допомогою шаблонної функції::

en: where ``id`` is any legal variable name. This function checks whether the additional information provided by the developer contains the name. If it does then the function assigns the provided value to a template local variable with that name. If the name is not in the additional information and if an ``expression`` is provided, the ``expression`` is evaluated and the result is assigned to the local variable. If neither a value nor an expression is provided, the function assigns the empty string (``''``) to the local variable.
uk: де записом ``ідентифікатор`` є будь-яка коректна назва змінної. Ця функція перевіряє, чи у додаткових відомостях, наданих розробником, міститься відповідна назва. Якщо це так, функція призначає надане значення змінної локальній змінній із вказаною назвою. Якщо назву змінної не буде виявлено у додаткових відомостях і якщо вказано ``вираз``, буде виконано обчислення ``виразу`` із призначенням результату локальній змінній. Якщо не буде знайдено ні значення, ні виразу, локальній змінній буде призначено порожній рядок (``''``).

en: A template can set a value in the ``globals`` dictionary using the template function::
uk: Шаблон може встановлювати значення у словнику ``globals`` за допомогою шаблонної функції::

en: This function sets the ``globals`` dictionary key:value pair ``id:value`` where ``value`` is the value of the template local variable ``id``. If that local variable doesn't exist then ``value`` is set to the result of evaluating ``expression``.
uk: Ця функція встановлює значення пари словника ``globals`` ключ:значення ``ідентифікатор:значення``, де ``значенням`` є значення локальної змінної шаблона ``ідентифікатор``. Якщо такої локальної змінної не існує, ``значення`` буде встановлено для результату обчислення ``виразу``.

en: Notes on the difference between modes
uk: Зауваження щодо відмінностей між режимами

en: The three program modes, :ref:`Single Function Mode <single_mode>` (SFM), :ref:`Template Program Mode <template_mode>` (`TPM`), and :ref:`General Program Mode <general_mode>` (`GPM`), work differently. SFM is intended to be 'simple' so it hides a lot of programming language bits.
uk: У роботі трьох режимів програмування, :ref:`режиму єдиної функції <single_mode>`, :ref:`режиму програмування шаблонів <template_mode>` та :ref:`загального режиму програмування <general_mode>` є відмінності. Режим єдиної функції є «простим», тому у ньому багато можливостей програмування «приховано».

en: Differences:
uk: Відмінності:

en: In SFM the value of the column is always passed as an 'invisible' first argument to a function included in the template.
uk: У режимі єдиної функції значення стовпчика завжди передається як «невидимий» перший аргумент функції, включено до шаблона.

en: SFM doesn't support the difference between variables and strings; all values are strings.
uk: У режимі єдиної функції не передбачено підтримки розрізнення між змінними і рядками; усі значення є рядками.

en: The following SFM template returns either the series name or the string "no series"::
uk: У наведеному нижче шаблоні режиму єдиної функції шаблон повертає або назву циклу, або рядок «no series»::

en: The equivalent template in `TPM` is ::
uk: Еквівалентний шаблон у режимі програмування шаблонів::

en: The equivalent template in `GPM` is::
uk: Еквівалентний шаблон у `режимі загального програмування`::

en: The first argument to ``ifempty`` is the value of the field ``series``. The second argument is the string ``no series``. In SFM the first argument, the value of the field, is automatically passed (the invisible argument).
uk: Першим аргументом ``ifempty`` є значення поля ``series``, а другим аргументом — рядок ``no series``. У режимі єдиної функції перший аргумент, значення поля, передається автоматично (невидимий аргумент).

en: Several template functions, for example ``booksize()`` and ``current_library_name()``, take no arguments. Because of the 'invisible argument' you cannot use these functions in SFM.
uk: Декілька шаблонних функцій, зокрема ``booksize()`` і ``current_library_name()``, не приймають аргументів. Через наявність невидимого аргументу ви не зможете скористатися цими функціями у режимі єдиної функції.

en: Nested functions, where a function calls another function to compute an argument, cannot be used in SFM. For example this template, intended to return the first 5 characters of the series value uppercased, won't work in SFM::
uk: У режимі єдиної функції не можна скористатися вкладеними функціями, коли одна з функцій викликає іншу функцію для обчислення свого аргументу. Наприклад, цей шаблон, який призначено для отримання перших 5 літер значення назви циклу у верхньому регістрі, не працюватиме у режимі єдиної функції::

en: `TPM` and `GPM` support nested functions. The above template in `TPM` would be::
uk: У шаблонному режимі програмування та загальному режимі програмування передбачено підтримку вкладених функцій. Наведений вище шаблон у шаблонному режимі програмування можна записати так::

en: In `GPM` it would be::
uk: У `загальному режимі програмування` це було б::

en: As noted in the above :ref:`Template Program Mode <template_mode>` section, using ``{`` and ``}`` characters in `TPM` string literals can lead to errors or unexpected results because they confuse the template processor. It tries to treat them as template boundaries, not characters. In some but not all cases you can replace a ``{`` with ``[[`` and a ``}`` with `]]`. Generally, if your program contains ``{`` and ``}`` characters then you should use `General Program Mode`.
uk: Як було зауважено вище у розділі :ref:`Режим програмування шаблонів <template_mode>`, використання символів ``{`` і ``}`` у рядкових літералах режиму програмування шаблонів може призвести до помилок або неочікуваних результатів, оскільки ці символи заважають нормальній роботі обробника шаблонів. Він намагається обробити їх як межі шаблона, а не символи. У деяких, але не в усіх випадках, ви можете замінити ``{`` на ``[[`` і ``}`` на `]]`. Загалом кажучи, якщо у вашій програмі є символи ``{`` і ``}``, вам слід користуватися `загальним режимом програмування`.

en: User-defined Python template functions
uk: Визначені користувачем шаблонні функції Python

en: You can add your own Python functions to the template processor. Such functions can be used in any of the three template programming modes. The functions are added by going to :guilabel:`Preferences -> Advanced -> Template functions`. Instructions are shown in that dialog. Note that you can use `Python Templates` for a similar purpose. As calling user-defined functions is faster than calling a Python template, user-defined functions might be more efficient depending on the complexity of what the function or template does.
uk: Ви можете додавати власні функції мовою Python до обробника шаблонів. Такими функціями можна скористатися в усіх трьох режимах програмування шаблонів. Додати функції можна за допомогою сторінки :guilabel:`Налаштування -> Додатково -> Шаблонні функції`. У діалоговому вікні, яке буде відкрито програмою, можна знайти відповідні настанови. Зауважте, що для досягнення тієї самої мети ви можете скористатися `Шаблонами Python`. Оскільки виклик визначених користувачем функцій є швидшим за виклик шаблона Python, визначені користувачем функції можуть бути ефективнішими, залежно від складності функції чи шаблона.

en: Special notes for using templates in different contexts
uk: Особливі нотатки щодо використання шаблонів у різних контекстах

en: In the GUI (:guilabel:`Columns made from other columns` and :guilabel:`Template searches`):
uk: У графічному інтерфейсі (:guilabel:`Стовпчики на основі інших стовпчиків` і :guilabel:`Шаблонні пошуки`):

en: GPM templates work as before.
uk: Шаблони GPM працюють так, як і у попередніх версіях.

en: Python templates have full access to the calibre database.
uk: Шаблони Python мають повний доступ до бази даних calibre.

en: In icon rules:
uk: У правилах піктограм:

en: icon rule templates have no book data so field-based functions such as :ref:`ff_format_date_field`, :ref:`ff_list_count_field`, and :ref:`ff_check_yes_no` won't work.
uk: шаблони правил піктограм не мають доступу до даних книги, а засновані на полях функції, зокрема :ref:`ff_format_date_field`, :ref:`ff_list_count_field` і :ref:`ff_check_yes_no` не працюватимуть.

en: In the Content server:
uk: У сервері даних:

en: Templates have access to the new API but not the old API (LibraryDatabase).
uk: Шаблони мають доступ до нового програмного інтерфейсу, але не до старого (LibraryDatabase).

en: Because of the above, the following formatter functions are not guaranteed to work in GPM templates (composite columns, icon rules, etc) and should be avoided if you use the content server:
uk: Через наведене вище, не можемо гарантувати працездатності вказаних нижче функцій у шаблонах GPM (складені стовпчики, правила піктограм тощо); не варто використовувати ці функції, якщо ви користуєтеся сервером даних:

en: Special notes for save/send templates
uk: Спеціальні нотатки щодо шаблонів збереження або надсилання

en: Special processing is applied when a template is used in a :guilabel:`Save to disk` or :guilabel:`Send to device` template. The values of the fields are cleaned, replacing characters that are special to file systems with underscores, including slashes. This means that field text cannot be used to create folders. However, slashes are not changed in prefix or suffix strings, so slashes in these strings will cause folders to be created. Because of this, you can create variable-depth folder structure.
uk: До шаблонів, які використовуються для дій :guilabel:`Зберегти на диск` і :guilabel:`Надіслати на пристрій`, застосовується спеціальна обробка. Значення полів буде очищено із заміною символів, які мають спеціальне значення у файлових системах, зокрема символів похилих рисок, на символи підкреслювання. Це означає, що текст поля не можна використовувати для створення тек. Втім, похилі риски не замінюватимуться у рядках префікса і суфікса, отже похилі риски у цих рядках можна використати для створення тек. Таким чином, ви можете створити структуру тек довільного рівня вкладеності.

en: For example, assume we want the folder structure `series/series_index - title`, with the caveat that if series does not exist, then the title should be in the top folder. The template to do this is::
uk: Наприклад, припустімо ми хочемо створити структуру тек `цикл/номер_у_циклі - назва`, із умовою, що якщо циклу не існує, назву слід розташувати у верхній теці. Шаблон для виконання цього завдання::

en: The slash and the hyphen appear only if series is not empty.
uk: Похила риска і дефіс мають з'являтися, лише якщо цикл не є порожнім.

en: The lookup function lets us do even fancier processing. For example, assume that if a book has a series, then we want the folder structure `series/series index - title.fmt`. If the book does not have a series then we want the folder structure `genre/author_sort/title.fmt`. If the book has no genre then we want to use 'Unknown'. We want two completely different paths, depending on the value of series.
uk: Функція `lookup` надає вам змогу виконувати виконувати навіть ще вишуканішу обробку. Наприклад, припустімо, що якщо книга належить до циклу, ми хочемо мати структуру тек `цикл/номер у циклі - назва.формат`. Якщо книга не належить до циклу, нам потрібна структура тек `жанр/упорядковане ім’я автора/назва.формат`. Якщо ж книга не належить до певного жанру, слід скористатися текою 'Unknown'. Нам потрібно два повністю різних шляхи, залежно від значення параметра циклу.

en: To accomplish this, we:
uk: Для виконання цього завдання ми:

en: Create a composite field (give it lookup name #aa) containing ``{series}/{series_index} - {title}``. If the series is not empty, then this template will produce `series/series_index - title`.
uk: Створимо складене поле (надавши йому назву #aa), що міститиме дані ``{series}/{series_index} - {title}``. Якщо значення циклу (series) є непорожнім, такий шаблон дасть нам `цикл/номер_у_циклі - назва`.

en: Create a composite field (give it lookup name #bb) containing ``{#genre:ifempty(Unknown)}/{author_sort}/{title}``. This template produces `genre/author_sort/title`, where an empty genre is replaced with `Unknown`.
uk: Створимо складене поле (надавши йому назву #bb) із вмістом ``{#genre:ifempty(Unknown)}/{author_sort}/{title}``. Цей шаблон дає `жанр/упорядковані_автори/назва`. Якщо немає даних щодо жанру, запис жанру буде замінено на `Unknown`.

en: Set the save template to ``{series:lookup(.,#aa,#bb)}``. This template chooses composite field ``#aa`` if series is not empty and composite field ``#bb`` if series is empty. We therefore have two completely different save paths, depending on whether or not `series` is empty.
uk: Встановимо шаблон збереження ``{series:lookup(.,#aa,#bb)}``. Цей шаблон вибирає складене поле ``#aa``, якщо значення запису циклу є непорожнім, і складене поле ``#bb``, якщо значення запису циклу є порожнім. Таким чином, ми матимемо повністю різні шляхи для збереження книг, залежно від того, чи є запис `series` порожнім.

en: Tips
uk: Підказки

en: Use the Template Tester to test templates. Add the tester to the context menu for books in the library and/or give it a keyboard shortcut.
uk: Для перевірки шаблонів скористайтеся засобом перевірки шаблонів. Додайте пункт засобу до контекстного меню для книг у бібліотеці і/або встановіть для нього клавіатурне скорочення.

en: Templates can use other templates by referencing composite columns built with the desired template. Alternatively, you can use Stored Templates.
uk: У шаблонах можна використовувати інші шаблони шляхом посилання на складені стовпчики, які побудовано за допомогою бажаних шаблонів. Крім того, ви можете скористатися «Збереженими шаблонами».

en: In a plugboard, you can set a field to empty (or whatever is equivalent to empty) by using the special template ``{}``. This template will always evaluate to an empty string.
uk: У наборі метаданих ви можете вказати порожні значення поля (або вказати будь-який еквівалент порожнього поля) за допомогою спеціального шаблона ``{}``. Цей шаблон завжди обробляється як порожній рядок.

en: The technique described above to show numbers even if they have a zero value works with the standard field series_index.
uk: Описана вище методика для показу чисел працює зі стандартним полем series_index, навіть якщо вміст відповідного поля є порожнім.

en: Template function reference
uk: Посилання на функцію шаблона
