Мова шаблонів calibre

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

Базова мова шаблонів є простою, але має потужні додаткові можливості. Шаблон складається з тексту і назв у фігурних дужках, які потім замінюються відповідними метаданими із оброблюваної книги. Наприклад, типовим шаблоном, що використовується у calibre для зберігання книг на пристрій, є таким:

{author_sort}/{title}/{title} - {authors}

Для книги «The Foundation» автора «Isaac Asimov» це буде так:

Asimov, Isaac/The Foundation/The Foundation - Isaac Asimov

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

{author_sort} Some Important Text {title}/{title} - {authors}

Для книги «The Foundation» автора «Isaac Asimov» це буде так:

Asimov, Isaac Some Important Text The Foundation/The Foundation - Isaac Asimov

У шаблоні ви можете використати усі різноманітні поля метаданих, які доступні у calibre, зокрема будь-які нетипові стовпчики, створені вами за допомогою «фільтрувальної назви». Щоб визначити фільтрувальну назву для стовпчика (поля), просто наведіть вказівник миші на заголовок стовпчика і зачекайте, доки з’явиться панель підказки. Назви для нетипових стовпчиків (стовпчиків, які було створено вами) завжди починаються з символу «#». Для нетипових стовпчиків типу циклу завжди передбачено додаткове поле із назвою #назвациклу_index, яке містить номер книги у циклі. Отже, якщо у вас є нетипове поле циклу із назвою #myseries, також існуватиме і поле #myseries_index.

Окрім полів, заснованих на вмісті стовпчиків, ви також можете використовувати:

{formats} - A list of formats available in the calibre library for a book
{identifiers:select(isbn)} - The ISBN of the book

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

{author_sort}/{series}/{title} {series_index}

Якщо книга належить до циклу, шаблон видасть таке:

Asimov, Isaac/Foundation/Second Foundation 3

а якщо книга не є частиною циклу, таке:

Asimov, Isaac/Second Foundation

(calibre автоматично вилучає кратні похилі риски та початкові і завершальні пробіли).

Додаткові можливості з форматування

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

По-перше, умовне включення тексту. Іноді може виникнути потреба у тому, щоб текст з’явився у виведених даних, лише якщо певне поле не є порожнім. Типовим випадком є поля series і series_index, які мають бути або одночасно порожніми або містити два значення із дефісом між ними. У calibre обробка цього випадку виконується за допомогою спеціального синтаксису полів.

Наприклад, якщо ви хочете скористатися шаблоном:

{series} - {series_index} - {title}

Якщо книга не належить до циклу, відповіддю буде - - назва. Багато хто б надав перевагу простому назва, без дефісів. Щоб досягти цього, скористайтеся розширеним синтаксисом {поле:|текст_префікса|текст_суфікса}. Якщо ви користуєтеся такою синтаксичною конструкцією, і у полі міститься значення «ЦИКЛ», результатом буде текст_префіксаЦИКЛтекст_суфікса. Якщо у полі немає значення, результатом буде порожній рядок; префікс і суфікс буде проігноровано. Префікс і суфікс можуть містити пробіли. Не використовуйте підшаблони (`{ … }`) або функції (див. нижче) як значення префікса або суфікса.

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

{series}{series_index:| - | - }{title}

Дефіси буде включено, лише якщо у книги є індекс у циклі, тобто якщо книга належить до певного циклу.

Зауваження: вам слід включити символ «:», якщо ви хочете скористатися префіксом або суфіксом. Також слід взагалі не використовувати символи | або використовувати обидва; скористатися лише одним, ось так: {поле:| - }, — не можна. Втім, можна використовувати порожнє значення для одного або іншого, ось так: {series:|| - }. Використання {title:||} є рівнозначним до використання {title}.

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

{series_index:0>3s} - Three digits with leading zeros

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

{series_index:>3s} - Three digits with leading spaces

Для кінцевих нулів скористайтеся такою конструкцією:

{series_index:0<3s} - Three digits with trailing zeros

Якщо ви використовуєте додаткові значення для номерів книг у циклах (наприклад, 1.1), може виникнути потреба у вирівнюванні розташування десяткової крапки. Наприклад, можна зробити так, щоб номери 1 і 2.5 було показано як 01.00 і 02.50, щоб їх можна було належними чином упорядкувати. Щоб досягти такого вирівнювання, скористайтеся таким кодом:

{series_index:0>5.2f} - Five characters, consisting of two digits with leading zeros, a decimal point, then 2 digits after the decimal point

Якщо вам потрібні лише перші дві літери даних, скористайтеся такою конструкцією:

{author_sort:.2} - Only the first two letter of the author sort name

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

Використання шаблонів у нетипових стовпчиках

Іноді потрібно зробити так, щоб метадані було видно, які calibre зазвичай не показує, або показати набір даних, який відрізняється від звичного набору даних calibre. Наприклад, у вас може виникнути потреба бачити ISBN, поле, вміст якого calibre не показує. Для показу таких даних ви можете скористатися нетиповими стовпчиками. Створіть стовпчик із типом «Стовпчик, створений на основі інших стовпчиків» (надалі ми такі стовпчики називатимемо складеними) і введіть до нього шаблон. Результат: calibre показуватиме у стовпчику результат обчислення шаблона. Для показу ISBN створіть стовпчик і введіть {identifiers:select(isbn)} у поле шаблона. Щоб створити стовпчик, який міститиме значення двох нетипових стовпчиків циклів, скористайтеся шаблоном {#series1:||,}{#series2}.

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

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

Використання функцій у шаблонах — режим єдиної функції

Припустімо, вам потрібно показати значення поля літерами верхнього регістру, хоча зазвичай вміст цього поля записується регістром символів як у заголовку. Досягти цього (як і багатьох інших речей) можна за допомогою функцій шаблонів. Наприклад, для переведення літер у верхній регістр можна скористатися ось таким шаблоном: {title:uppercase()}. Для показу назви у форматі, типовому для заголовків, скористайтеся шаблоном {title:titlecase()}.

Функції мають з’являтися у частині форматування, після : і перед першим | або кінцевою }. Якщо у шаблоні мають бути і форматування, і функція, функцію слід вказати після ще одного символу :. Записи функцій мають завжди завершуватися символами (). Деяким функціям передаються додаткові значення (аргументи), такі значення вказують у дужках, ().

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

Синтаксичною конструкцією для функцій є {поле:функція(аргументи)} або {поле:функція(аргументи)|префікс|суфікс}. Аргументи відокремлюються один від одного комами. Коми у аргументах слід екранувати символом зворотної похилої риски ( «» ). Останній (або єдиний) аргумент функції не повинен містити кінцевої дужки ( «)» ). Функції повертають значення поля, використаного у шаблоні, із відповідними змінами.

Важливе зауваження: якщо у вас є досвід програміста, будь ласка, майте на увазі, що синтаксис у цьому режимі (єдиної функції) може бути трохи неочікуваним. Рядки не беруться у лапки. Пробіли є значимими. Усі аргументи мають бути сталими. Не передбачено підлеглого обчислення. Не використовуйте підшаблонів (`{ … }`) у аргументах функцій. Замість них використовуйте шаблонний режим програмування та загальний режим програмування.

У багатьох функціях використовуються формальні вирази. У всіх випадках відповідність формальним виразам встановлюється без врахування регістру символів.

Нижче наведено список доступних функцій. Зауважте, що повну документацію щодо функцій наведено у розділі Довідник з функцій:

  • lowercase() — повернути значення поля символами нижнього регістру.

  • uppercase() — повернути значення поля символами верхнього регістру.

  • titlecase() — повернути значення поля так, щоб усі перші літери слів були великими, а решта символів слів — символами нижнього регістру.

  • capitalize() — повернути значення поля так, щоб перша літера була літерою верхнього регістру символів, а решта літер — літерами нижнього регістру символів.

  • contains(взірець, текст для відповідності, текст для невідповідності) — перевіряє, чи міститься у значенні відповідник формального виразу «взірець». Повертає «текст для відповідності», якщо буде знайдено відповідник, інакше повертає «текст для невідповідності».

  • count(роздільник) — за заданим значенням списком пунктів, відокремлених роздільником «роздільник», повертає кількість пунктів у списку. У більшості списків як роздільник використовується кома, для авторів може використовуватися амперсанд. Приклади: {tags:count(,)}, {authors:count(&)}

  • format_number(шаблон) — вважати поле числом і форматувати число на основі шаблону форматування python, наприклад «{0:5.2f}», «{0:,d}» або «${0:5,.2f}». Частина назви поля у шаблоні має дорівнювати 0 (нулеві) («{0:» у наведених вище прикладах). Ви можете не вказувати початкового «{0:» і завершального «}», якщо у шаблоні усього один формат. З докладнішими прикладами можна ознайомитися за допомогою документації до мови шаблонів та документації з Python. Повертає порожній рядок, якщо виконати форматування не вдасться.

  • human_readable() — очікує, що значення є числом, і повертає рядкове представлення числа у кілобайтах, мегабайтах, гігабайтах тощо.

  • ifempty(текст) — якщо поле не є порожнім, повернути значення поля. Якщо поле є порожнім, повернути текст.

  • in_list(значення, роздільник, взірець, значення_якщо_знайдено, значення_якщо_не_знайдено) — обробляє поле як список пунктів, відокремлених роздільником, порівнює взірець з кожним зі значень у списку. Якщо рядок збігається зі значенням, повертає «значення_якщо_знайдено», інакше повертає «значення_якщо_не_знайдено». Значення «взірець» і «значення_якщо_знайдено» можна повторювати довільну кількість разів, залежно від пошуку. Перевірка взірців виконується послідовно. Функція повертає перший знайдений відповідник.

  • language_codes(рядки_мов) — повертає коди мов для рядків, переданих як рядки_мов`. Рядками мають бути записи у поточній локалі. Окремі записи у параметрі рядки_мов слід відокремлювати комами.

  • language_strings(коди_мов, локалізація) — повертає рядки кодів мов, передані як коди_мов`. Якщо значенням параметра «локалізація» є нуль, рядки буде повернуто англійською. Якщо значенням параметра «локалізація» є ненульове значення, рядки буде повернуто у поточній локалі. Параметр «коди_мов» слід вказувати у форматі списку, розділеного комами.

  • list_item(номер, роздільник) — обробляє значення як список пунктів, відокремлених роздільником «роздільник», повертає пункт з номером «номер». Перший пункт має номер нуль. Останній з пунктів можна отримати за допомогою «list_item(-1, роздільник)». Якщо пункту немає у списку, буде повернуто порожнє значення. Роздільник має те саме значення, що і у функції count.

  • lookup(взірець, поле, взірець, поле, ..., інше_поле) — подібна до switch, але аргументами є назви полів (метадані), а не текст. Значення відповідного поля буде отримано і використано. Зауважте, що оскільки складені стовпчики є полями, ви можете скористатися цією функцією у одному зі складених полів, щоб скористатися значенням одного з інших складених полів. Дуже корисно для побудови змінних адрес для збереження даних (докладніше далі).

  • rating_to_stars(use_half_stars) — повертає оцінку як рядок символів-зірочок. Початковим значенням має бути число від 0 до 5. Встановіть для use_half_stars значення 1, якщо вам потрібні половинні символи зірочок для нетипових стовпчиків оцінок, значення у яких не є цілими, наприклад, рівними 2.5.

  • re(взірець, замінник) — повертає вміст поля після застосування заміни за формальним виразом. Всі екземпляри рядка «взірець» буде замінено рядком «замінник». Як і всюди у calibre, має бути використано формальні вирази, сумісні з синтаксисом Python.

  • select(ключ) — вважати вміст поля списком елементів, відокремлених один від одного комами, де елементи записано у формі «ідентифікатор:значення». Шукає пару із ідентифікатором, який відповідає значенню «ключ» і повертає відповідне ідентифікатору значення. Ця функція може стати у пригоді при видобуванні значення, подібного до ISBN, з набору ідентифікаторів книги.

  • shorten(ліві символи, текст посередині, праві символи) — повертає скорочену версію поля, що складається з «ліві символи» символів з початку поля, потім символів «текст посередині», а потім «праві символи» символів наприкінці рядка. Значення «ліві символи» та «праві символи» мають бути цілі числа. Розгляньмо приклад з назвою книги «Давні англійські закони часів Айвенго» і вам потрібно вмістити цю назву у 15 символів. Якщо ви скористаєтеся шаблоном {title:shorten(9,-,5)}, результатом буде «Давні анг-венго». Якщо кількість символів у полі менша за суму «ліві символи» + «праві символи» + кількість символів у «текст посередині», вміст поля не змінюватиметься. У нашому прикладі назву «Під мінаретами» не буде змінено.

  • str_in_list(роздільник, рядок, значення_якщо_знайдено, значення_якщо_не_знайдено) — обробляє поле як список пунктів, відокремлених роздільником, порівнює рядок з кожним зі значень у списку. Якщо рядок збігається зі значенням (без врахування регістру), повертає «значення_якщо_знайдено», інакше повертає «значення_якщо_не_знайдено». Якщо рядок містить роздільники, його також буде оброблено як список, перевірятиметься кожне зі значень у цьому списку. Значення «рядок» і «значення_якщо_знайдено» можна повторювати довільну кількість разів, залежно від пошуку. Перевірка рядків виконується послідовно. Функція повертає перший знайдений відповідник.

  • subitems(початковий_номер, кінцевий_номер) — цією функцією користуються для розбиття списків пунктів, зокрема списків жанрів. Функція обробляє поле як відокремлений комами список записів, у якому кожен з записів є відокремленим крапками списком. Повертає новий список, створений таким чином: спочатку буде знайдено всі відокремлені крапками запис, потім для кожного такого запису буде видобуто компоненти від номера початковий_номер до кінцевий_номер, а потім всі видобуті записи знову буде поєднано для отримання результату. Перший компонент у відокремленому крапками списку матиме номер нуль. Якщо номер буде від’ємним, його буде відраховано від кінця списку. Якщо буде вказано кінцевий_номер рівний нулеві, номер вважатиметься кінцевим у списку. Приклади:

    Assuming a #genre column containing "A.B.C":
        {#genre:subitems(0,1)} returns "A"
        {#genre:subitems(0,2)} returns "A.B"
        {#genre:subitems(1,0)} returns "B.C"
    Assuming a #genre column containing "A.B.C, D.E":
        {#genre:subitems(0,1)} returns "A, D"
        {#genre:subitems(0,2)} returns "A.B, D.E"
    
  • sublist(початковий_номер, кінцевий_номер, роздільник) — обробляє поле як список пунктів, відокремлених роздільником роздільник, повертає новий список, створений з пунктів з номера початковий_номер до номера кінцевий_номер. Перший пункт має нульовий номер. Якщо вказано від’ємний номер, його буде відраховано від кінця списку. Якщо буде вказано кінцевий_номер рівний нулеві, номер вважатиметься кінцевим у списку. Приклади у основному режимі шаблонів зі стовпчиком міток (значення у якому відокремлено комами), що містить значення «A, B, C»:

    {tags:sublist(0,1,\,)} returns "A"
    {tags:sublist(-1,0,\,)} returns "C"
    {tags:sublist(0,-1,\,)} returns "A, B"
    
  • swap_around_articles(роздільник) — повертає значення із артиклями, які пересунуто в кінець. Значенням може бути список, елементи якого буде оброблено окремо. Якщо значенням є список, вам слід вказати роздільник значень у списку. Якщо значення роздільника вказано не буде, значення вважатиметься одним рядком, а не списком.

  • swap_around_comma() — за заданим полем у форматі «B, A» повертає значення «A B». Найкорисніше для перетворення імен у форматі «Прізвище, Ім’я» на імена у форматі «Ім’я Прізвище». Якщо коми у значенні не буде виявлено, функція поверне значення без змін.

  • switch(значення, взірець, значення, взірець, значення, ..., інше_значення) — для кожної пари «взірець, значення» перевіряє, чи відповідає поле формальному виразу «взірець». Якщо це так, повертає «значення». Якщо відповідності з взірцем не буде знайдено, буде повернено «інше_значення». Можна визначати довільну кількість пар «взірець, значення»..

  • test(текст для непорожнього, текст для порожнього) — повертає «текст для непорожнього», якщо значення не є порожнім. Якщо це не так, повертає «текст для порожнього»..

  • transliterate() — повертає такий рядок латинською абеткою, який при читанні за звуком літер звучить приблизно так само, як і початкове поле. Наприклад, якщо початковим рядком є Фёдор Миха́йлович Достоевский, функцією буде повернуто Fiodor Mikhailovich Dostoievskii.

Тепер, як щодо використання функцій і форматування у одному полі? Припустімо, у нас є нетиповий стовпчик із назвою #myint, у якому містяться цілі числа. Вам потрібно представити їх у форматі із початковими нулями, ось так: 003. Для цього можна було б скористатися форматуванням 0>3s. Втім, типово, якщо число (ціле або дійсне) дорівнює нулеві, у поле буде записано порожнє значення. Отже, нульові значення початкові значення призводитимуть до порожніх записів, а не до записів 000. Якщо вам потрібні саме значення 000, вам слід скористатися одразу і рядком форматування, і функцією ifempty для заміни порожнього значення на нульове. Еталонний код міг би бути таким:

{#myint:0>3s:ifempty(0)}

Зауважте, що ви також можете скористатися префіксом та суфіксом. Якщо вам потрібно, щоб число було записано як [003] або [000], скористайтеся таким полем:

{#myint:0>3s:ifempty(0)|[|]}

Складніші функції у шаблонах — режим програмування шаблонів

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

У програмному режимі шаблонів ви можете використовувати документовані вище функції. Докладніший опис використання наведено нижче.

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

{#series:'ifempty($, field('#genre'))'}

Приклад демонструє декілька речей:

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

  • змінна $ позначає поле, яке обробляє вираз; у нашому випадку це #series.

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

  • пробіли буде проігноровано; їх можна використовувати будь-де у виразі.

  • сталі рядки слід брати у відповідні лапки ' або ".

Синтаксис мови викладено у наведеній нижче граматиці. Обговорення щодо «compare», «if_expression» і «template_call» наведено у розділі Загальний режим програмування::

program         ::= expression_list
expression_list ::= expression [ ';' expression ]*
expression      ::= identifier | constant | function | assignment | compare | if_expression
function        ::= identifier '(' expression [ ',' expression ]* ')'
compare         ::= expression compare_op expression
compare_op      ::= '==' | '!=' | '>=' | '>' | '<=' | '<' | '==#' | '!=#' | '>=#' | '>#' | '<=#' | '<#'
if_expression   ::= 'if' expression 'then' expression_list [elif_expression] ['else' expression_list] 'fi'
elif_expression ::= 'elif' expression 'then' expression_list elif_expression | ''
assignment      ::= identifier '=' expression
constant        ::= " string " | ' string ' | number
identifier      ::= sequence of letters or ``_`` characters

Коментарями вважаються рядки, які починаються з символу «#».

expression без помилок завжди містить значення. Значенням expression_list є значення останнього виразу у списку. Отже, значенням такої програми (expression_list):

1; 2; 'foobar'; 3

дорівнює 3.

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

{series_index:'
    substr(
        strcat($, '->',
            cmp(divide($, 2), 1,
                assign(c, 1); substr('lt123', c, 0),
                'eq', 'gt')),
        0, 6)
   '| prefix | suffix}

Програма виконує такі дії:

  • визначає, що полем, яке слід знайти, є поле series_index. Його вміст визначає значення змінної $.

  • викликає функцію substr, яка приймає 3 параметри (рядок, початок, кінець). Функція повертає рядок, який сформовано видобуванням символів від символу з номером початок до символу з номером кінець з рядка str. Нумерація символів починається з нуля (перший символ рядка має номер 0). У цьому прикладі рядок буде визначено функцією strcat, початком є 0, а кінцем — 6. Отже, буде повернуто перші 6 символів рядка, який повертається strcat, і який має бути визначено до того, як substr зможе повернути значення.

  • викликає функцію strcat (об’єднання рядків). Strcat приймає 1 або декілька аргументів і повертає рядок, що складається з об’єднання всіх аргументів. У цьому випадку аргументів три. Першим є значення у змінній $, яким є значення series_index. Другим є сталий рядок '->'. Третім аргументом є значення, яке повертає функція cmp, тобто значення, яке має бути повністю обчислено до того, як strcat зможе повернути значення.

  • функція cmp приймає 5 аргументів, (x, y, lt, eq, gt). Вона порівнює x та y і повертає третій аргумент, lt, якщо x < y, четвертий аргумент, eq, якщо x == y, і п’ятий аргумент, gt, якщо x > y. Як в усіх функцій, усі аргументи функції можуть бути інструкціями. У нашому випадку перший аргумент (значення x) є результатом ділення series_index на 2. Другий аргумент, y, є сталою 1. Третій аргумент, lt, інструкцією (докладніше про неї нижче). Четвертий аргумент, eq, є сталим рядком 'eq'. А п’ятий аргумент є сталим рядком 'gt'.

  • Третій аргумент (той, що стоїть на місці lt) є інструкцією або послідовністю виразів. Слід пам’ятати, що інструкція (послідовність відокремлених символом крапки з комою виразів) також є виразом, що повертає значення останнього виразу у списку. У нашому випадку, програма спочатку надає локальній змінній c значення 1, потім повертає підрядок, утворений видобуванням рядка, що починається з символу із номером c і завершується кінцевим символом рядка. Оскільки c завжди містить сталу 1, завжди повертатиметься рядок, що починається з другого символу рядка і завершується його кінцевим символом, або 't123'.

  • Щойно інструкцію, яка надає значення третього параметра, буде виконано, cmp зможе повернути значення. Після цього значення зможуть повернути strcat`, а потім і ``substr. Програма завершить свою роботу.

Для різних значень series_index програма повертає:

  • series_index == undefined, result = prefix ->t123 suffix

  • series_index == 0.5, result = prefix 0.50-> suffix

  • series_index == 1, result = prefix 1->t12 suffix

  • series_index == 2, result = prefix 2->eq suffix

  • series_index == 3, result = prefix 3->gt suffix

У програмному режимі можна використовувати усі функції, які було описано у розділі щодо режиму єдиної функції. Для цього вам слід надати значення, яке може бути оброблено функцією як перший параметр, окрім параметрів, які вказано вище. Наприклад, у програмному режимі параметрами функції test є test(x, текст для непорожнього, текст для порожнього). Параметр x, який є значенням, щодо якого слід виконати перевірку, майже завжди є змінною або результатом виклику функції, часто field().

Описані нижче функції розширюють набір функцій, описаний у розділі щодо режиму єдиної функції. Не забудьте, що, як можна побачити у наведеному вище прикладі, функції з режиму єдиної функції потребують додаткового першого параметра, який визначає поле, яке має обробляти функція. Окрім параметра ідентифікатор функції assign, усі параметри можуть бути інструкціями (послідовностями виразів). Зауважте, що із повною документацією щодо функцій можна ознайомитися у розділі Довідник з функцій:

  • and(значення, значення, …) — повертає рядок «1», якщо всі значення не є порожніми. Якщо одне зі значень є порожнім, повертає порожній рядок. Ця функція добре поєднується з test або first_non_empty. Ви можете вказати довільну кількість значень.

  • add(x, y) — повертає суму x + y. Повідомляє про виключення, якщо x або y не є числом.

  • assign(ідентифікатор, значення) — надає ідентифікатору значення, потім повертає значення. «ідентифікатор» має бути ідентифікатором, а не виразом.

  • approximate_formats() — повернути розділений комами список форматів, які на певному етапі було пов’язано з книгою``. Гарантувати чинність такого списку не можна, хоча, ймовірно, він залишається чинним. Цю функцію можна викликати у режимі шаблонної програми за допомогою шаблона «{:“approximate_formats()“}». Зауважте, що назви форматів завжди слід вказувати великими літерами, ось так: EPUB.

  • author_links(роздільник_значень, роздільник_пар) — повертає рядок, що містить список авторів з відповідними пов’язаними значеннями у форматі автор1 роздільник_значень посилання_автора1 роздільник_пар автор2 роздільник_значень посилання_автора2 тощо. Запис автора буде відділено від пов’язаного із ним значення рядком роздільник_значень без додаткових пробілів. Пари автор-пов’язане значення буде відокремлено рядком роздільник_пар без додаткових пробілів. Ви можете вибирати рядки роздільників довільним чином, так, щоб вони не збігалися з іменами авторів або посиланнями. Запис автора буде включено, навіть якщо пов’язане з ним значення посилання є порожнім.

  • author_sorts(роздільник_значень) — повертає рядок, що містить список значень упорядкування записів авторів книги. Критерієм упорядковування є один із записів метаданих автора (відмінний від author_sort у книгах). Повернутий список має такий формат: упорядкування автора 1 роздільник_значень упорядкування автора 2 тощо. Значення упорядковування авторів у цьому списку перебувають у тому самому порядку, що і автори у книзі. Якщо вам потрібні пробіли навколо роздільника_значень, додайте їх до рядка роздільника.

  • booksize() — повертає значення поля calibre «size». Повертає „“, якщо форматів немає.

  • check_yes_no(назва_поля, is_undefined, is_false, is_true) — перевіряє, чи дорівнює значення поля «так/ні», вказаного ключем пошуку назва_поля, значенню, вказаному параметрами, повертає «yes», якщо знайдено відповідник, інакше, повертає порожній рядок. Встановіть для параметрів is_undefined, is_false або is_true значення 1 (число), щоб перевірити відповідну умову, інакше, встановіть 0. Приклад:

    check_yes_no("#bool", 1, 0, 1)
    

    повертає «yes», якщо поле «так/ні» "#bool" або не визначено (ні True, ні False), або True. Встановлювати значення 1 можна для декількох параметрів з набору is_undefined, is_false та is_true. Зазвичай, ця функція використовується у функціях test() або is_empty().

  • ceiling(x) — повертає найменше ціле число, яке є більшим або рівним x. Надсилає виключення, якщо x не є числом.

  • cmp(x, y, lt, eq, gt) — порівнює x і y після перетворення обох величин у числа``. Повертає lt, якщо x < y. Повертає eq, якщо x == y. За інших умов повертає gt.

  • connected_device_name(розташування_сховища) — якщо пристрій з’єднано, повертає назву пристрою, якщо ні — порожній рядок. Кожне розташування сховища даних на пристрої може мати власну назву. Назви розташувань: «“main», «carda» і «cardb». Ця функція працює лише у графічному інтерфейсі користувача.

  • current_library_name() — повертає останню адресу поточної бібліотеки calibre. Цю функцію можна викликати у режимі програмування шаблону за допомогою шаблону «{:“current_library_name()“}».

  • current_library_path() — повернути шлях до поточної бібліотеки calibre. Цю функцію можна викликати у режимі шаблонної програми за допомогою шаблона «{:“current_library_path()“}».

  • days_between(дата1, дата2) — повертає кількість днів між датою дата1 і датою дата2``. Кількість днів є додатною, якщо дата1 перевищує дата2, інакше значення буде від’ємним. Якщо значення дата1 або значення дата2 не вдасться обробити як дату, функція поверне порожній рядок.

  • divide(x, y) — повертає частку x / y. Повідомляє про виключення, якщо x або y не є числом.

  • ``eval(рядок) — обробляє рядок як програму з передаванням локальних змінних (змінних, які було визначено за допомогою «assign»). Це надає змогу скористатися обробником шаблонів для побудови складних результатів на основі локальних змінних. Оскільки символи «{» і «}» є особливими, вам слід використовувати «[[» для позначення символу «{» і «]]» для позначення символу «}». Перетворення буде виконано автоматично. Також слід зауважити, що у аргументі цієї функції не можна використовувати префікси і суфікси (тобто синтаксичні конструкції, подібні до «|префікс|суфікс»), якщо використовується режим програмного шаблона.

  • field(назва) — повертає значення поля метаданих, вказаного параметром «назва».

  • finish_formatting(значення, формат, префікс, суфікс) — застосувати формат, префікс і суфікс до значення у спосіб, у який це виконується шаблоном, зокрема {series_index:05.2f| - |- }. Цю функцію створено для спрощення перетворення складних шаблонів режиму єдиної функції і програмного режиму до загального програмного режиму (див. нижче) для використання переваг компіляції шаблонів загального програмного режиму. Наприклад, наведена нижче програма виводить ті самі дані, що і вказаний вище програма-шаблон:

    program: finish_formatting(field("series_index"), "05.2f", " - ", " - ")
    

    Інший приклад. Для шаблона {series:re(([^\s])[^\s]+(\s|$),\1)}{series_index:0>2s| - | - }{title} скористайтеся таким:

    program:
        strcat(
            re(field('series'), '([^\s])[^\s]+(\s|$)', '\1'),
            finish_formatting(field('series_index'), '0>2s', ' - ', ' - '),
            field('title')
        )
    
  • first_matching_cmp(значенняl, умова1, результат1, умова2, результат2, ..., інший_результат) — послідовно виконує порівняння «val < cmpN», повертаючи результатN для першої з виконаних умов у послідовності. Повертає інший_результат, якщо жодну з умов не буде виконано. Приклад:

    first_matching_cmp(10,5,"small",10,"middle",15,"large","giant")
    

    повертає «large». Той самий приклад із першим значенням 16 повертатиме «giant».

  • first_non_empty(значення, значення, ...) — повертає перше значення, яке не є порожнім. Якщо всі значення є порожніми, повертає порожнє значення. Ви можете вказати довільну кількість значень.

  • floor(x) — повертає найбільше ціле число, яке є меншим або рівним x. Надсилає виключення, якщо x не є числом.

  • format_date(значення, рядок_формату) — форматувати значення, яке має бути записом поля дати, на основі значення рядок_формату, повернути рядок. Коди форматування:

    d    : the day as number without a leading zero (1 to 31)
    dd   : the day as number with a leading zero (01 to 31)
    ddd  : the abbreviated localized day name (e.g. "Mon" to "Sun").
    dddd : the long localized day name (e.g. "Monday" to "Sunday").
    M    : the month as number without a leading zero (1 to 12).
    MM   : the month as number with a leading zero (01 to 12)
    MMM  : the abbreviated localized month name (e.g. "Jan" to "Dec").
    MMMM : the long localized month name (e.g. "January" to "December").
    yy   : the year as two digit number (00 to 99).
    yyyy : the year as four digit number.
    h    : the hours without a leading 0 (0 to 11 or 0 to 23, depending on am/pm)
    hh   : the hours with a leading 0 (00 to 11 or 00 to 23, depending on am/pm)
    m    : the minutes without a leading 0 (0 to 59)
    mm   : the minutes with a leading 0 (00 to 59)
    s    : the seconds without a leading 0 (0 to 59)
    ss   : the seconds with a leading 0 (00 to 59)
    ap   : use a 12-hour clock instead of a 24-hour clock, with 'ap' replaced by the localized string for am or pm.
    AP   : use a 12-hour clock instead of a 24-hour clock, with 'AP' replaced by the localized string for AM or PM.
    iso  : the date with time and timezone. Must be the only format present.
    

    Результати можуть бути не такими, на які ви сподівалися, якщо форматована дата містить локалізовані назви місяців, що може трапитися, якщо ви змінили коригування формату на такі, які містять MMMM. У цьому випадку, замість використання шаблона, подібного до {pubdate:format_date(yyyy)}, напишіть шаблон, що використовує програмний режим, ось так: {:'format_date(raw_field('pubdate'),'yyyy')'}.

  • formats_modtimes(формат_дати) — повертає відокремлений комами список відокремлених двокрапками пунктів, які відповідають часу внесення змін до файлів форматів книги. Параметр «формат_дати» визначає спосіб форматування дати. Докладніше про цей формат можна дізнатися з опису функції format_date(). Для отримання даних щодо внесення змін до одного з форматів ви можете скористатися функцією select. Зауважте, що назви форматів буде вказано великими літерами, наприклад EPUB.

  • formats_paths() — повернути розділений комами список розділених двокрапками записів, щоб відповідають шляхам до файлів книги у різних форматах. Для отримання шляху до файла певного формату ви можете скористатися функцією select. Зауважте, що назви форматів слід вказувати великими літерами, ось так: EPUB.

  • formats_sizes() — повертає відокремлений комами список відокремлених двокрапками пунктів, які відповідають об’єму у байтах файлів форматів книги. Для отримання даних щодо об’єму файла у одному з форматів ви можете скористатися функцією select. Зауважте, що назви форматів буде вказано великими літерами, наприклад EPUB.

  • fractional_part(x) — повертає дробову частину десяткового числа. Наприклад, fractional_part(3.14) дорівнює 0.14. Надсилає виключення, якщо x не є числом.

  • has_cover() — повертає «Yes», якщо у книги є зображення обкладинки, інакше повертає порожній рядок

  • not(значення) — повертає рядок «1», якщо значення не є порожнім. Якщо значення є порожнім, повертає порожній рядок. Ця функція добре поєднується з test або first_non_empty.

  • list_difference(список1, список2, роздільник) — повертає список, створений вилученням зі списку список1 всіх пунктів, які містяться у списку список2, на основі порівняння без врахування регістру. Пункти у списках список1 і список2 відокремлюються роздільником «роздільник», як і пункти у повернутому функцією списку.

  • list_equals(список1, роздільник1, список2, роздільник2, значення_якщо_так, значення_якщо_ні) — повертає «значення_якщо_так», якщо список1 і список2 містять однакові записи. Якщо це не так, повертає «значення_якщо_ні». Записи визначаються поділом кожного зі списків на основі вказаного символу роздільника (роздільник1 або роздільник2). Порядок записів у списках не береться до уваги. Порівняння виконуватиметься без врахування регістру символів.

  • list_intersection(список1, список2, роздільник) — повертає список, створений вилученням зі списку список1 всіх пунктів, яких немає у списку список2, на основі порівняння без врахування регістру. Пункти у списках список1 і список2 відокремлюються роздільником «роздільник», як і пункти у повернутому функцією списку.

  • list_re(початковий_список, роздільник, фв_пошуку, пар_заміни) — будує список таким чином: спочатку поділяє початковий_список на запис на основі вказаного символу роздільника`. Для кожного з записів у списку перевіряє відповідність формальному виразу «фв_пошуку». Якщо відповідність буде встановлено, запис буде додано до повернутого списку. Якщо параметр «пар_заміни» не буде порожнім, заміну буде виконано до додавання запису до повернутого списку.

  • list_re_group(список_джерел, роздільник, фв_включення, фв_пошуку, шаблон_групи_1, шаблон_групи_2, ...) — Подібне до list_re, але замінники є обов’язковими. Використовує re_group(пункт_списку, фв_пошуку, шаблон_групи_, ) під час виконання замін у остаточному списку.

  • list_sort(список, напрямок, роздільник) — повертає список, впорядкований без врахування регістру. Якщо значенням параметра «напрямок» є нуль, список буде впорядковано за зростанням. Якщо значення буде іншим, список впорядковуватиметься за спаданням. Записи у початковому списку має бути відокремлено роздільником, як і записи у списку-результаті.

  • list_union(список1, список2, роздільник) — повертає список, створений за допомогою об’єднання пунктів у списках список1 і список2 з вилученням дублікатів, виявлених шляхом порівняння без врахування регістру символів. Якщо записи пунктів відрізнятимуться лише регістром символів, використовуватиметься пункт зі списку список1. Пункти у списках список1 і список2 має бути відокремлено роздільником, який також буде використано під час формування списку-результату.

  • mod(x) -— повертає лишок від ділення x на y, де x, y та результат є цілими числами. Надсилає виключення, якщо x або y не є числом.

  • multiply(x, y) — повертає добуток x * y. Повідомляє про виключення, якщо x або y не є числом.

  • ondevice() — повертає «Yes», якщо встановлено «ondevice», інакше повертає порожній рядок

  • or(значення, значення, …) — повертає рядок «1», якщо хоч одне значення не є порожнім. Якщо всі значення є порожніми, повертає порожній рядок. Ця функція добре поєднується з test або first_non_empty. Ви можете вказати довільну кількість значень.

  • print(a, b, …) — виводить аргументи до стандартного виведення. Якщо ви не запускали calibre з командного рядка (calibre-debug -g), дані нікуди не буде виведено.

  • raw_field(назва) — повертає поле метаданих, вказане за допомогою параметра «назва», без застосування форматування.

  • raw_list(назва, роздільник) — повертає список метаданих з назвою «назва» без застосування будь-якого форматування або упорядковування. Записи у списку буде відокремлено значенням «роздільник».

  • re_group(значення, зразок, шаблон_для_групи_1, шаблон_для_групи_2, ...) — повертає рядок, створений за допомогою застосування формального виразу заданого зразком до значення та заміною кожної з відповідних груп значенням, повернутим відповідним шаблоном. Початкове відповідне значення для групи позначається $. У режимі шаблонного програмування, як і у функціях template та eval, замість { слід використовувати [[, замість } — ]]. Приклад: у режимі шаблонного програмування знайти послідовності з понад одного слова і замінити першу літеру першого слова на велику:

    {series:'re_group($, "(\S* )(.*)", "[[$:uppercase()]]", "[[$]]")'}
    
  • round(x) — повертає найближче до x ціле число. Надсилає виключення, якщо x не є числом.

  • series_sort() — повертає значення впорядкування циклу.

  • strcat(a, b, …) — може приймати довільну кількість аргументів. Повертає рядок, отриманий з’єднанням всіх аргументів..

  • strcat_max(максимум, рядок1, префікс2, рядок2, …) — повертає рядок, утворений об’єднанням аргументів функції. Початковим значенням результату буде рядок1. Пари «префікс, рядок» додаватимуться в кінець результату, якщо довжина рядка-результату не перевищуватиме значення «максимум». Значення рядок1 буде повернуто, навіть якщо довжина рядка рядок1 перевищує максимум. Функції можна передавати довільну кількість пар «префікс, рядок».

  • strcmp(x, y, lt, eq, gt) — виконує порівняння x і y як рядків без врахування регістру. Повертає lt, якщо x < y. Повертає eq, якщо x == y. За інших умов повертає gt.

  • strlen(a) — повертає довжину рядка, переданого як аргумент..

  • substr(рядок, початок, кінець) — повертає символи від символу з номером «початок» до символу з номером «кінець» у рядку «рядок»````. Вважається, що у рядок починається з нульового символу. Якщо значення «кінець» є від’ємним, символи буде відраховано у напрямку до початку рядка. Якщо значенням «кінець» є нуль, кінцем вважатиметься останній символ. Приклади: substr(„12345“, 1, 0) повертає „2345“, а substr(„12345“, 1, -1) повертає „234“.

  • subtract(x, y) — повертає різницю x - y. Повідомляє про виключення, якщо x або y не є числом.

  • today() — повертає сьогоднішню дату. Це значення створено для використання у format_date або days_between, але з ним можна працювати як зі звичайним рядком. Дату буде повернуто у форматі ISO.

  • template(x) — обробляє x як шаблон. Обробку буде виконано у власному контексті, тобто змінні не використовуватимуться як спільні для функції виклику і обробки шаблону. Оскільки символи «{» і «}» є особливими, вам слід використовувати «[[» для позначення символу «{» і «]]» для позначення символу «}». Перетворення буде виконано автоматично. Наприклад, template(„[[title_sort]]“) буде оброблено як шаблон {title_sort} і повернуто відповідне значення. Також слід зауважити, що у аргументі цієї функції не можна використовувати префікси і суфікси (тобто синтаксичні конструкції, подібні до «|префікс|суфікс»), якщо використовується режим програмного шаблона.

Використання загального режиму програмування

У складніших шаблонних програмах часто простіше уникати синтаксису шаблонів (усіх символів { і }) і писати програми у класичному стилі. Перейти до такого режиму у calibre можна розпочавши шаблон зі слова program:. Шаблонні програми програми компілюються і виконуються. Обробка шаблонів (форматування, обробка префіксів, суфіксів) не виконується. Значення для спеціальної змінної $ не встановлюватиметься.

Однією з переваг режиму program: є те, що дужки у ньому вже не є спеціальними символами. Наприклад, немає потреби у використанні [[ і ]] при використанні функції template(). Ще однією перевагою є зручність у читанні.

У обох режимах програмування, загальному і шаблонному, передбачено можливість використання виразів if із таким синтаксисом:

if <<expression>> then
    <<expression_list>>
[elif <<expression>> then <<expression_list>>]*
[else <<expression_list>> ]
fi

Частина із elif та else є необов’язковою. Слова if, then, elif, else і fi є зарезервованими. Ви не можете використовувати їх як назви ідентифікаторів. Додавати розриви рядків та пробіли можна будь-де, де це має сенс. <<expression>> є одинарним виразом мови шаблонів. Не можна використовувати у цьому виразі крапку з комою. <<expression_list>> — послідовність відокремлених крапкою з комою виразів мови шаблонів, яка включає вкладені if. Приклади:

  • program: if field('series') then 'yes' else 'no' fi

  • program: if field('series') then a = 'yes'; b = 'no' else a = 'no'; b='yes' fi; strcat(a, '-', b)

  • Приклад вкладеного``if``:

    program:
        if field('series')
        then
            if check_yes_no(field('#mybool'), '', '', '1')
            then
                'yes'
            else
                'no'
            fi
        else
            'no series'
        fi
    

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

  • program: if field('series') then 'foo' else 'bar' fi

  • program: if field('series') then a = 'foo' else a = 'bar' fi; a

  • program: a = if field('series') then 'foo' else 'bar' fi; a

  • program: a = field(if field('series') then 'series' else 'title' fi); a

У режимі програмування також передбачено підтримку класичних реляційних (порівняльних) операторів: ==, !=, <, <=, >, >=. Оператори повертають „1“, якщо умова справджується, і „“, якщо ні. Ці оператори виконують порівняння рядків без врахування регістру символів із використанням лексичного порядку. Приклади:

  • program: field('series') == 'foo' повертає „1“, якщо циклом книги є „foo“.

  • program: if field('series') != 'foo' then 'bar' else 'mumble' fi повертає „bar“, якщо циклом книги не є „foo“, а інакше, повертає „mumble“.

  • program: if or(field('series') == 'foo', field('series') == '1632') then 'yes' else 'no' fi повертає „yes“, якщо циклом є „foo“ або „1632“, а інакше, повертає „no“.

  • program: if '11' > '2' then 'yes' else 'no' fi повертає „no“, оскільки це лексичне порівняння. Якщо вам потрібне порівняння чисел, а не лексичне порівняння, скористайтеся операторами ==#, !=#, <#, <=#, >#, >=#. У цьому випадку для лівого і правого операндів встановлюються нульові значення, якщо їх не визначено, або вони дорівнюють порожньому рядку. Якщо операнди не є числами, буде повідомлено про помилку.

У загальному режимі програмування передбачено можливість збереження шаблонів загального режиму програмування та виклику цих шаблонів з інших шаблонів. Зберегти шаблони можна за допомогою пункту Налаштування → Додатково → Шаблонні функції. у відповідному діалоговому вікні буде наведено довідкову інформації. Викликати шаблон можна у той самий спосіб, що і функцію, передавши йому, якщо потрібно, позиційні аргументи. Аргументом може бути будь-який вираз. Приклади виклику шаблону, де ми припускаємо, що збережений шаблон має назву foo:

  • foo() — виклик шаблону без передавання аргументів.

  • foo(a, b) — виклик шаблону з передаванням значень двох змінних — a і b.

  • foo(if field('series') then field('series_index') else 0 fi) — якщо книга належить до циклу, передати номер книги у циклі, інакше — передати значення 0.

У збереженому шаблоні отримання аргументів відбувається за допомогою виклику функції arguments. Ця функція одразу оголошує і ініціалізує локальні змінні, які виконують роль параметрів. Ці змінні є позиційними — їм надається значення, яке стоїть у виклику на відповідній позиції. Якщо відповідне значення змінної не було надано у виклику, arguments надає параметру типового значення. Якщо типове значення не вказано, змінній буде надано значення порожнього рядка. Наприклад, наведена нижче функція arguments оголошує 2 змінні — key, alternate:

arguments(key, alternate='series')

У наведених нижче прикладах знову припускаємо, що збережений шаблон має назву foo:

  • foo('#myseries') — аргумент key матиме значення myseries, а аргумент alternate матиме значення series.

  • foo('series', '#genre') — змінній key буде надано значення series, а змінній alternate — значення #genre.

  • foo() -— змінній key буде надано значення порожнього рядка, а змінній alternate — значення #genre.

Простим способом тестування збережених шаблонів є використання вікна Засіб тестування шаблонів. Надайте цьому вікну клавіатурного скорочення за допомогою пункту Налаштування → Додатково → Клавіатурні скорочення → Засіб тестування шаблонів. Надання клавіатурного скорочення вікну Збережені шаблони допоможе вам швидше перемикатися між тестуванням та редагування початкового коду збереженого шаблону.

Зауваження щодо відмінностей між режимами

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

Приклад: у наведеному нижче шаблоні режиму єдиної функції шаблон повертає або назву циклу, або рядок «no series»:

{series:ifempty(no series)}

Еквівалентний шаблон у режимі програмування шаблонів:

``{series:'ifempty($, 'no series')'}``

Еквівалентний шаблон у режимі загального програмування:

``program: ifempty(field('series'), 'no series')``

Першим аргументом ifempty є значення поля series, а другим аргументом — рядок no series. У режимі єдиної функції перший аргумент, значення поля, передається автоматично (невидимий аргумент).

Декілька шаблонних функцій, зокрема booksize() і current_library_name(), не приймають аргументів. Через наявність невидимого аргументу ви не зможете скористатися цими функціями у режимі єдиної функції.

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

``{series:uppercase(substr(0,5))}``

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

``{series:'uppercase(substr($, 0,5))'}``

У загальному режимі програмування це було б:

``program: uppercase(substr(field('series'), 0,5))``

Визначені користувачем шаблонні функції Python

Ви можете додавати власні функції мовою Python до обробника шаблонів. Такими функціями можна скористатися в усіх трьох режимах програмування шаблонів. Додати функції можна за допомогою сторінки Налаштування  →  Додатково  →  Шаблонні функції. У діалоговому вікні, яке буде відкрито програмою, можна знайти відповідні настанови.

Спеціальні нотатки щодо шаблонів збереження або надсилання

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

Наприклад, припустімо ми хочемо створити структуру тек цикл/номер_у_циклі - назва, із умовою, що якщо циклу не існує, назву слід розташувати у верхній теці. Шаблон для виконання цього завдання:

{series:||/}{series_index:|| - }{title}

Похила риска і дефіс мають з’являтися, лише якщо цикл не є порожнім.

Функція lookup надає вам змогу виконувати виконувати навіть ще вишуканішу обробку. Наприклад, припустімо, що якщо книга належить до циклу, ми хочемо мати структуру тек цикл/номер у циклі - назва.формат. Якщо книга не належить до циклу, нам потрібна структура тек жанр/упорядковане ім’я автора/назва.формат. Якщо ж книга не належить до певного жанру, слід скористатися текою „Unknown“. Нам потрібно два повністю різних шляхи, залежно від значення параметра циклу.

Для виконання цього завдання ми:
  1. Створимо складене поле (надавши йому назву #AA), що міститиме дані {series}/{series_index} - {title}. Якщо значення циклу (series) є непорожнім, такий шаблон дасть нам цикл/номер_у_циклі - назва.

  2. Створимо складене поле (надавши йому назву #BB) із вмістом {#genre:ifempty(Unknown)}/{author_sort}/{title}. Цей шаблон дає жанр/упорядковані_автори/назва. Якщо немає даних щодо жанру, запис жанру буде замінено на Unknown.

  3. Встановимо шаблон збереження {series:lookup(.,#AA,#BB)}. Цей шаблон вибирає складене поле #AA, якщо значення запису циклу є непорожнім, і складене поле #BB, якщо значення запису циклу є порожнім. Таким чином, ми матимемо повністю різні шляхи для збереження книг, залежно від того, чи є запис series порожнім.

Шаблони і набори метаданих

Набори метаданих використовуються для внесення змін до метаданих, що записуються до книг під час дій із надсилання на пристрій і збереження на диск. Набір метаданих надає вам змогу вказати шаблон для надання даних, які слід записати до метаданих книги. Ви можете скористатися наборами метаданих для внесення змін до таких полів: authors, author_sort, language, publisher, tags, title, title_sort. Набори метаданих допомагають у використанні спеціалізованих метаданих для книг на пристрої з метою усування проблем із упорядковуванням книг або їхнім показом.

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

Якщо до метаданих може бути застосовано набір (на сервері даних, для збереження на диск або надсилання на пристрій), calibre шукає визначені набори метаданих і вибирає належний для заданого формату і пристрою. Наприклад, для того, щоб знайти належний набір метаданих для книги EPUB, яку надсилають на пристрій під керуванням ANDROID, calibre шукає набори метаданих у такому порядку:

  • набір метаданих із точною відповідністю за форматом і пристроєм, наприклад EPUB і ANDROID

  • набір метаданих із точним відповідником за форматом і спеціальним варіантом any device, наприклад EPUB і any device

  • набір метаданих із спеціальним варіантом any format і точною відповідністю за пристроєм, наприклад any format і ANDROID

  • набір метаданих any format і any device

Поля міток (tags) і авторів (authors) обробляються у особливий спосіб, оскільки у обох цих полях може міститися декілька записів. У книги може бути багато міток і багато авторів. Якщо ви визначаєте одне з цих двох полів як таке, вміст якого слід змінити, результати використання шаблона буде перевірено на наявність декількох записів. Для міток результат буде розділено на записи за знайденими calibre комами. Наприклад, якщо шаблон створює значення Трилер, Жахи, результатом буде дві мітки, Трилер і Жахи. Способів додавання коми у окрему мітку не передбачено.

Те саме стосується авторів, але для поділу на записи використовується інший символ, & (амперсанд), а не кома. Наприклад, якщо шаблоном створюється значення Blogs, Joe&Posts, Susan, для книги буде визначено двоє авторів, Blogs, Joe і Posts, Susan. Якщо ж шаблон створює значення Blogs, Joe;Posts, Susan, книга матиме один запис автора із доволі чудернацьким іменем.

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

Підказки

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

  • Для перевірки шаблонів скористайтеся засобом перевірки шаблонів. Додайте пункт засобу до контекстного меню для книг у бібліотеці і/або встановіть для нього клавіатурне скорочення.

  • Шаблони можуть використовувати інші шаблони, посилаючись на складені стовпчики, які побудовано на основі бажаного шаблону. Крім того, можна скористатися збереженими шаблонами.

  • У наборі метаданих ви можете вказати порожні значення поля (або вказати будь-який еквівалент порожнього поля) за допомогою спеціального шаблона {}. Цей шаблон завжди обробляється як порожній рядок.

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