Jazyk šablón calibre¶

Jazyk šablón calibre je jazyk špecifický pre calibre, ktorý sa v calibre používa na úlohy, ako je zadávanie ciest k súborom, formátovanie hodnôt a výpočet hodnôt pre používateľom definované stĺpce. Príklady:

Zadanie štruktúry priečinkov a názvov súborov pri ukladaní súborov z knižnice calibre na disk alebo do čítačky e-kníh.
Definovanie pravidiel na pridávanie ikon a farieb do zoznamu kníh calibre.
Definovanie virtuálnych stĺpcov, ktoré obsahujú údaje z iných stĺpcov.
Pokročilé vyhľadávanie v knižnici.
Pokročilé hľadanie a nahrádzanie metadát.

Jazyk je postavený na koncepte šablóny, ktorá určuje, ktoré metadáta knihy použiť, aké výpočty na týchto metadátach vykonať a ako ich naformátovať.

Základné šablóny¶

Základná šablóna pozostáva z jedného alebo viacerých výrazov šablóny. Výraz šablóny pozostáva z textu a názvov v zložených zátvorkách ({}), ktoré sa nahradia zodpovedajúcimi metadátami spracúvanej knihy. Napríklad predvolená šablóna v calibre používaná na ukladanie kníh do zariadenia má 4 výrazy šablóny:

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

Pre knihu „The Foundation“ od „Isaac Asimov“ bude mať šablóna podobu:

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

Lomítka nie sú výrazy šablóny, pretože nie sú medzi {}. Takýto text ostáva tam, kde sa nachádza. Napríklad, ak je šablóna:

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

potom pre „The Foundation“ šablóna vytvorí:

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

Výraz šablóny môže pristupovať ku všetkým metadátam dostupným v calibre, vrátane vlastných stĺpcov (stĺpcov, ktoré si sami vytvoríte), pomocou vyhľadávacieho názvu stĺpca. Ak chcete nájsť vyhľadávací názov pre stĺpec (niekedy nazývaný pole), podržte kurzor myši nad hlavičkou stĺpca v zozname kníh calibre. Vyhľadávacie názvy vlastných stĺpcov vždy začínajú znakom #. Pre stĺpce typu séria existuje dodatočné pole s názvom #lookup name_index, čo je index série pre danú knihu v sérii. Ak máte napríklad vlastný stĺpec série s názvom #myseries, bude existovať aj stĺpec s názvom #myseries_index. Index štandardného stĺpca série sa nazýva series_index.

Okrem štandardných polí založených na stĺpcoch môžete použiť aj:

{formats} – zoznam formátov dostupných v knižnici calibre pre danú knihu

{identifiers:select(isbn)} – ISBN knihy

Ak metadáta pre dané pole pre danú knihu nie sú definované, pole v šablóne sa nahradí prázdnym reťazcom (''). Napríklad zvážte nasledujúcu šablónu:

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

Ak je Asimovova kniha „Second Foundation“ v sérii „Foundation“, šablóna vytvorí:

Asimov, Isaac/Foundation/Second Foundation 3

Ak pre knihu nebola zadaná séria, šablóna vytvorí:

Asimov, Isaac/Second Foundation

Procesor šablón automaticky odstráni viacnásobné lomítka a úvodné alebo koncové medzery.

Pokročilé formátovanie¶

Okrem nahradenia metadát môžu šablóny podmienečne zahrnúť dodatočný text a ovládať, ako sa nahradené údaje formátujú.

Podmienečné zahrnutie textu

Niekedy chcete, aby sa text v výstupe zobrazil iba vtedy, ak pole nie je prázdne. Bežným prípadom je series a series_index, kde chcete buď nič, alebo dve hodnoty oddelené spojovníkom. calibre tento prípad rieši pomocou špeciálnej syntaxe výrazu šablóny.

Napriklad, s použitím vyššie uvedeného príkladu Foundation, predpokladajme, že chcete, aby šablóna vytvorila Foundation - 3 - Second Foundation. Táto šablóna vytvára tento výstup:

{series} - {series_index} - {title}

Ak však kniha nemá sériu, šablóna vytvorí - - názov, čo pravdepodobne nie je to, čo chcete. Ľudia zvyčajne chcú, aby výsledkom bol názov bez nadbytočných spojovníkov. Môžete to dosiahnuť pomocou nasledujúcej syntaxe šablóny:

{field:|prefix_text|suffix_text}

Tento výraz šablóny hovorí, že ak field má hodnotu XXXX, výsledok bude prefix_textXXXXXsuffix_text. Ak je field prázdne (nemá hodnotu), výsledkom bude prázdny reťazec (nič), pretože predpona a prípona sa ignorujú. Predpona a prípona môžu obsahovať medzery.

Nepoužívajte podšablóny (`{ … }`) ani funkcie (pozri nižšie) v predpone alebo prípone.

Pomocou tejto syntaxe môžeme vyriešiť vyššie uvedený problém s chýbajúcou sériou pomocou šablóny:

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

Spojovníky sa zahrnú iba vtedy, ak kniha má index série, ktorý má iba vtedy, ak má sériu. Pokračujúc v príklade Foundation, šablóna vytvorí Foundation - 1 - Second Foundation.

Poznámky:

Ak používate predponu alebo príponu, musíte za vyhľadávacím názvom uviesť dvojbodku.
Musíte použiť buď žiadny, alebo oba znaky |. Použitie jedného, ako v {field:| - }, nie je povolené.
Je v poriadku neuviesť text pre predponu ani pre príponu, ako v {series:|| - }. Šablóna {title:||} je rovnaká ako {title}.

Formátovanie

Predpokladajme, že chcete, aby series_index bol naformátovaný ako tri číslice s úvodnými nulami. Toto to zabezpečí:

{series_index:0>3s} – tri číslice s úvodnými nulami

Pre koncové nuly použite:

{series_index:0<3s} – tri číslice s koncovými nulami

Ak používate indexy sérií s desatinnými hodnotami, napr. 1,1, možno budete chcieť, aby sa desatinné bodky zarovnali. Napríklad môžete chcieť, aby sa indexy 1 a 2,5 zobrazili ako 01,00 a 02,50, aby sa správne zoradili v zariadení, ktoré vykonáva lexikálne triedenie. Ak to chcete urobiť, použite:

{series_index:0>5.2f} – päť znakov pozostávajúcich z dvoch číslic s úvodnými nulami, desatinnej bodky a potom 2 číslic za desatinnou bodkou.

Ak chcete iba prvé dva znaky údajov, použite:

{author_sort:.2} – iba prvé dva znaky názvu triedenia autora

Veľká časť formátovania jazyka šablón calibre pochádza z Pythonu. Podrobnejšie informácie o syntaxi týchto pokročilých formátovacích operácií nájdete v dokumentácii Pythonu.

Použitie šablón na definovanie vlastných stĺpcov¶

Šablóny možno použiť na zobrazenie informácií, ktoré nie sú v metadátach calibre, alebo na zobrazenie metadát inak, než je bežný formát calibre. Môžete napríklad chcieť zobraziť ISBN, pole, ktoré calibre nezobrazuje. Môžete to dosiahnuť vytvorením vlastného stĺpca typu Stĺpec vytvorený z iných stĺpcov (ďalej len zložené stĺpce) a zadaním šablóny na generovanie zobrazovaného textu. Stĺpec bude zobrazovať výsledok vyhodnotenia šablóny. Ak chcete napríklad zobraziť ISBN, vytvorte stĺpec a do poľa šablóny zadajte {identifiers:select(isbn)}. Ak chcete zobraziť stĺpec obsahujúci hodnoty dvoch vlastných stĺpcov série oddelené čiarkou, použite {#series1:||,}{#series2}.

Zložené stĺpce môžu používať akúkoľvek možnosť šablóny vrátane formátovania.

Poznámka: Údaje zobrazené v zloženom stĺpci nemôžete upravovať. Namiesto toho upravujte zdrojové stĺpce. Ak upravíte zložený stĺpec, napríklad dvojitým kliknutím naň, calibre otvorí na úpravu šablónu, nie podkladové údaje.

Šablóny a plugboardy¶

Plugboardy sa používajú na zmenu metadát zapisovaných do kníh počas operácií odosielania do zariadenia a ukladania na disk. Plugboard vám umožňuje určiť šablónu, ktorá poskytuje údaje na zápis do metadát knihy. Plugboardy môžete použiť na úpravu nasledujúcich polí: authors, author_sort, language, publisher, tags, title, title_sort. Táto funkcia pomáha ľuďom, ktorí chcú v knihách v zariadeniach používať iné metadáta, aby vyriešili problémy s triedením alebo zobrazením.

Pri vytváraní plugboardu určíte formát a zariadenie, pre ktoré sa má plugboard použiť. K dispozícii je špeciálne zariadenie save_to_disk, ktoré sa používa pri ukladaní formátov (na rozdiel od ich odosielania do zariadenia). Po výbere formátu a zariadenia vyberiete polia metadát, ktoré sa majú zmeniť, a zadáte šablóny, ktoré poskytnú nové hodnoty. Tieto šablóny sú prepojené s cieľovými poľami, odtiaľ názov plugboardy. V týchto šablónach môžete samozrejme použiť zložené stĺpce.

Plugboardy sú pomerne flexibilné a možno ich písať v režime jednej funkcie, režime programu šablóny, všeobecnom programovom režime alebo režime šablóny Python.

Keď by sa plugboard mohol použiť (server obsahu, uloženie na disk alebo odoslanie do zariadenia), calibre prehľadá definované plugboardy a vyberie ten správny pre daný formát a zariadenie. Napríklad na nájdenie vhodného plugboardu pre knihu EPUB odosielanú do zariadenia ANDROID calibre prehľadá plugboardy v nasledujúcom poradí:

plugboard s presnou zhodou formátu a zariadenia, napr. EPUB a ANDROID
plugboard s presnou zhodou formátu a špeciálnou voľbou akékoľvek zariadenie, napr. EPUB a akékoľvek zariadenie
plugboard so špeciálnou voľbou akýkoľvek formát a presnou zhodou zariadenia, napr. akýkoľvek formát a ANDROID
plugboard s akýkoľvek formát a akékoľvek zariadenie

Polia tags a authors majú špeciálne zaobchádzanie, pretože obe tieto polia môžu obsahovať viac ako jednu položku. Kniha môže mať veľa značiek a veľa autorov. Keď určíte, že sa má zmeniť jedno z týchto dvoch polí, skúma sa výsledok šablóny, či obsahuje viac ako jednu položku. Pri značkách sa výsledok rozdelí všade, kde calibre nájde čiarku. Napríklad, ak šablóna vytvorí hodnotu Thriller, Horror, výsledkom budú dve značky, Thriller a Horror. Neexistuje spôsob, ako vložiť čiarku do stredu značky.

To isté sa deje pri autoroch, ale s použitím iného znaku na rozdelenie, znaku & (ampersand) namiesto čiarky. Napríklad, ak šablóna vytvorí hodnotu Blogs, Joe&Posts, Susan, kniha bude mať dvoch autorov, Blogs, Joe a Posts, Susan. Ak šablóna vytvorí hodnotu Blogs, Joe;Posts, Susan, kniha bude mať jedného autora s pomerne zvláštnym menom.

Plugboardy ovplyvňujú metadáta zapísané do knihy pri jej uložení na disk alebo zápise do zariadenia. Plugboardy neovplyvňujú metadáta používané funkciami save to disk a send to device na vytváranie názvov súborov. Názvy súborov sa namiesto toho vytvárajú pomocou šablón zadaných v príslušnom okne nastavení.

Použitie funkcií v šablónach – režim jednej funkcie¶

Predpokladajme, že chcete zobraziť hodnotu poľa veľkými písmenami, keď je toto pole zvyčajne v type title case. Môžete to urobiť pomocou funkcií šablóny. Napríklad na zobrazenie názvu veľkými písmenami použite funkciu uppercase, ako v {title:uppercase()}. Na zobrazenie v type title case použite {title:titlecase()}.

Funkcie patria do časti formátu šablóny, za : a pred prvým | alebo zatváracou }, ak sa nepoužíva predpona/prípona. Ak máte aj formát, aj odkaz na funkciu, funkcia nasleduje po druhej :. Funkcie vracajú hodnotu stĺpca určeného v šablóne, vhodne upravenú.

Syntax na použitie funkcií je jedna z:

{lookup_name:function(arguments)}
{lookup_name:format:function(arguments)}
{lookup_name:function(arguments)|prefix|suffix}
{lookup_name:format:function(arguments)|prefix|suffix}

Za názvami funkcií vždy musia nasledovať otváracie a zatváracie zátvorky. Niektoré funkcie vyžadujú ďalšie hodnoty (argumenty) a tie patria do zátvoriek. Argumenty sa oddeľujú čiarkami. Literálne čiarky (čiarky ako text, nie oddeľovače argumentov) musia byť uvedené spätným lomítkom (\). Posledný (alebo jediný) argument nemôže obsahovať textovú zatváracu zátvorku.

Funkcie sa vyhodnocujú pred špecifikáciami formátu a predponou/príponou. Nižšie nájdete príklad použitia formátu aj funkcie.

Dôležité: Ak máte programátorské skúsenosti, všimnite si, že syntax v režime jednej funkcie nie je to, čo očakávate. Reťazce nie sú v úvodzovkách a medzery sú významné. Všetky argumenty sa považujú za konštanty; neexistujú žiadne výrazy.

Nepoužívajte podšablóny (`{ … }`) ako argumenty funkcií. Namiesto toho použite Režim programu šablóny a Všeobecný programový režim.

Poznámky k volaniu funkcií v režime jednej funkcie:

Keď sa funkcie používajú v režime jednej funkcie, prvý parameter value sa automaticky nahradí obsahom poľa určeného v šablóne. Napríklad pri spracovaní šablóny {title:capitalize()} sa obsah poľa title odovzdá ako parameter value funkcii capitalize.
V dokumentácii funkcií zápis [niečo]* znamená, že sa niečo môže opakovať nula alebo viackrát. Zápis [niečo]+ znamená, že sa niečo opakuje jeden alebo viackrát (musí existovať aspoň raz).
Niektoré funkcie používajú regulárne výrazy. V jazyku šablón sa pri porovnávaní regulárnych výrazov nerozlišujú veľké a malé písmená.

Funkcie sú zdokumentované v Príručka funkcií šablóny. Dokumentácia vám povie, aké argumenty funkcie vyžadujú a čo robia. Napriklad tu je dokumentácia funkcie ifempty.

ifempty(value, text_if_empty) – ak value nie je prázdna, vráti túto value, inak vráti text_if_empty.

Vidíte, že funkcia vyžaduje dva argumenty, value a text_if_empty. Keďže však používame režim jednej funkcie, argument value vynechávame a odovzdávame iba text_if_empty. Napríklad táto šablóna:

{tags:ifempty(No tags on this book)}

zobrazuje značky knihy, ak nejaké má. Ak nemá žiadne značky, zobrazí No tags on this book.

Nasledujúce funkcie sú použiteľné v režime jednej funkcie, pretože ich prvý parameter je value.

capitalize(value) – vráti value s prvým písmenom veľkým a zvyškom malým.
ceiling(value) – vráti najmenšie celé číslo väčšie alebo rovné value.
cmp(value, y, lt, eq, gt) – porovná value a y po prevedení oboch na čísla.
contains(value, pattern, text_if_match, text_if_not_match) – skontroluje, či hodnota zodpovedá regulárnemu výrazu pattern.
date_arithmetic(value, calc_spec, fmt) – Vypočíta nový dátum z value pomocou calc_spec.
encode_for_url(value, use_plus) – vráti value zakódovanú na použitie v URL podľa use_plus. Hodnota sa najprv zakóduje pre URL. Potom, ak je use_plus 0, medzery sa nahradia znakmi '+' (plus). Ak je 1, medzery sa nahradia %20.
floor(value) – vráti najväčšie celé číslo menšie alebo rovné value.
format_date(value, format_string) – naformátuje value, ktorá musí byť reťazcom dátumu, pomocou format_string a vráti reťazec.
format_duration(value, template, [largest_unit]) – naformátuje hodnotu, počet sekúnd, na reťazec zobrazujúci týždne, dni, hodiny, minúty a sekundy. Ak je hodnota desatinné číslo, zaokrúhli sa na najbližšie celé číslo.
format_number(value, template) – interpretuje value ako číslo a formátuje toto číslo pomocou formátovacej šablóny jazyka Python, ako {0:5.2f}, {0:,d} alebo ${0:5,.2f}.
fractional_part(value) – vráti časť hodnoty za desatinnou čiarkou.
human_readable(value) – očakáva, že value je číslo, a vráti reťazec reprezentujúci toto číslo v KB, MB, GB atď.
ifempty(value, text_if_empty) – ak value nie je prázdna, vráti túto value, inak vráti text_if_empty.
language_strings(value, localize) – vráti názvy jazykov pre jazykové kódy (zoznam názvov a kódov nájdete tu) odovzdané v value.
list_contains(value, separator, [ pattern, found_val, ]* not_found_val) – interpretuje value ako zoznam položiek oddelených separator, pričom porovnáva pattern s každou položkou v zozname.
list_count(value, separator) – interpretuje hodnotu ako zoznam položiek oddelených separator a vráti počet položiek v zozname.
list_count_matching(value, pattern, separator) – interpretuje value ako zoznam položiek oddelených separator a vráti počet položiek v zozname, ktoré zodpovedajú regulárnemu výrazu pattern.
list_item(value, index, separator) – interpretuje value ako zoznam položiek oddelených separator a vráti položku na pozícii ‚index‘.
list_sort(value, direction, separator) – vráti value zoradenú pomocou lexikálneho zoradenia nerozlišujúceho veľkosť písmen.
lookup(value, [ pattern, key, ]* else_key) – vzory sa budú postupne porovnávať s value.
lowercase(value) – vráti value malými písmenami.
mod(value, y) – vráti floor zvyšku value / y.
rating_to_stars(value, use_half_stars) – Vráti value ako reťazec znakov hviezdičky (★).
re(value, pattern, replacement) – vráti value po použití regulárneho výrazu.
re_group(value, pattern [, template_for_group]*) – vráti reťazec vytvorený použitím regulárneho výrazu pattern na value a nahradením každého zhodného výskytu
round(value) – vráti najbližšie celé číslo k value.
select(value, key) – interpretuje value ako čiarkami oddelený zoznam položiek, pričom každá položka má formát id:id_value (formát identifikátora calibre).
shorten(value, left_chars, middle_text, right_chars) – vráti skrátenú verziu value
str_in_list(value, separator, [ string, found_val, ]+ not_found_val) – interpretuje value ako zoznam položiek oddelených separator a potom porovná string s každou hodnotou v zozname.
subitems(value, start_index, end_index) – táto funkcia rozdeľuje zoznamy hierarchických položiek podobných značkám, ako sú žánre.
sublist(value, start_index, end_index, separator) – interpretuje value ako zoznam položiek oddelených separator a vráti nový zoznam vytvorený z položiek od start_index po end_index.
substr(value, start, end) – vráti znaky od start-teho do end-teho znaku reťazca value.
swap_around_articles(value, separator) – vráti value s členmi presunutými na koniec, oddelenými bodkočiarkou.
swap_around_comma(value) – pre value v tvare B, A, vráti A B.
switch(value, [patternN, valueN,]+ else_value) – pre každú dvojicu patternN, valueN skontroluje, či value zodpovedá regulárnemu výrazu patternN
test(value, text_if_not_empty, text_if_empty) – vráti text_if_not_empty, ak hodnota nie je prázdna, inak vráti text_if_empty.
titlecase(value) – vráti value s veľkými začiatočnými písmenami.
transliterate(value) – Vráti reťazec v latinskej abecede vytvorený priblížením zvuku slov vo value.
uppercase(value) – vráti value veľkými písmenami.

Použitie funkcií a formátovania v tej istej šablóne

Predpokladajme, že máte celočíselný vlastný stĺpec #myint, ktorý chcete zobraziť s úvodnými nulami, ako napríklad 003. Jedným spôsobom je použiť formát 0>3s. Ak sa však číslo (celé alebo desatinné) rovná nule, v predvolenom nastavení sa hodnota zobrazí ako prázdny reťazec, takže nulové hodnoty vytvoria prázdny reťazec, nie 000. Ak chcete vidieť hodnoty 000, použite formátovací reťazec aj funkciu ifempty na zmenu prázdnej hodnoty späť na nulu. Šablóna by bola:

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

Upozorňujeme, že môžete použiť aj predponu a príponu. Ak chcete, aby sa číslo zobrazilo ako [003] alebo [000], použite šablónu:

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

Všeobecný programový režim¶

Všeobecný programový režim (GPM) nahrádza výrazy šablóny programom napísaným v jazyku šablón. Syntax tohto jazyka je definovaná nasledujúcou gramatikou:

program         ::= 'program:' expression_list
expression_list ::= top_expression [ ';' top_expression ]*
top_expression  ::= or_expression
or_expression   ::= and_expression [ '||' and_expression ]*
and_expression  ::= not_expression [ '&&' not_expression ]*
not_expression  ::= [ '!' not_expression ]* | concatenate_expr
concatenate_expr::= compare_expr [ '&' compare_expr ]*
compare_expr    ::= add_sub_expr [ compare_op add_sub_expr ]
compare_op      ::= '==' | '!=' | '>=' | '>' | '<=' | '<' |
                    'in' | 'inlist' | 'inlist_field' |
                    '==#' | '!=#' | '>=#' | '>#' | '<=#' | '<#'
add_sub_expr    ::= times_div_expr [ add_sub_op times_div_expr ]*
add_sub_op      ::= '+' | '-'
times_div_expr  ::= unary_op_expr [ times_div_op unary_op_expr ]*
times_div_op    ::= '*' | '/'
unary_op_expr   ::= [ add_sub_op unary_op_expr ]* | expression
expression      ::= identifier | constant | function | assignment | field_reference |
                    if_expr | for_expr | break_expr | continue_expr | return_stmt
                    '(' expression_list ')' | function_def
field_reference ::= '$' [ '$' ] [ '#' ] identifier
identifier      ::= id_start [ id_rest ]*
id_start        ::= letter | underscore
id_rest         ::= id_start | digit
constant        ::= " string " | ' string ' | number
function        ::= identifier '(' expression_list [ ',' expression_list ]* ')'
function_def    ::= 'def' identifier '(' top_expression [ ',' top_expression ]* ')' ':'
                    expression_list 'fed'
assignment      ::= identifier '=' top_expression
if_expr         ::= 'if' condition 'then' expression_list
                    [ elif_expr ] [ 'else' expression_list ] 'fi'
condition       ::= top_expression
elif_expr       ::= 'elif' condition 'then' expression_list elif_expr | ''
for_expr        ::= for_list | for_range
for_list        ::= 'for' identifier 'in' list_expr
                    [ 'separator' separator_expr ] ':' expression_list 'rof'
for_range       ::= 'for' identifier 'in' range_expr ':' expression_list 'rof'
range_expr      ::= 'range' '(' [ start_expr ',' ] stop_expr
                    [ ',' step_expr [ ',' limit_expr ] ] ')'
with_expr       ::= 'with' top_expression ':' expression_list 'htiw'
list_expr       ::= top_expression
break_expr      ::= 'break'
continue_expr   ::= 'continue'
return_stmt     ::= 'return' top_expression
separator_expr  ::= top_expression
start_expr      ::= top_expression
stop_expr       ::= top_expression
step_expr       ::= top_expression
limit_expr      ::= top_expression

Poznámky:

top_expression má vždy hodnotu. Hodnota expression_list je hodnota posledného top_expression v zozname. Napríklad hodnota zoznamu výrazov 1;2;'foobar';3 je 3.
V logickom kontexte je akákoľvek neprázdna hodnota True
V logickom kontexte je prázdna hodnota False
Reťazce a čísla možno používať zameniteľne. Napríklad 10 a '10' sú to isté.
Komentáre sú riadky začínajúce znakom „#“, prípadne predchádzané medzerami alebo tabulátormi.

Priorita operátorov

Priorita operátorov (poradie vyhodnocovania) od najvyššej (vyhodnotí sa ako prvá) po najnižšiu (vyhodnotí sa ako posledná) je:

Volania funkcií, konštanty, výrazy v zátvorkách, príkazové výrazy, priraďovacie výrazy, odkazy na polia.
Unárne plus (+) a mínus (-). Tieto operátory sa vyhodnocujú sprava doľava.

Tieto a všetky ostatné aritmetické operátory vracajú celé čísla, ak výsledok výrazu má desatinnú časť rovnú nule. Napríklad, ak výraz vráti 3.0, zmení sa na 3.
Násobenie (*) a delenie (/). Tieto operátory sú asociatívne a vyhodnocujú sa zľava doprava. Ak chcete zmeniť poradie vyhodnocovania, použite zátvorky.
Sčítanie (+) a odčítanie (-). Tieto operátory sú asociatívne a vyhodnocujú sa zľava doprava.
Číselné a reťazcové porovnania. Tieto operátory vracajú '1', ak porovnanie uspeje, inak prázdny reťazec (''). Porovnania nie sú asociatívne: a < b < c je syntaktická chyba.
Zreťazenie reťazcov (&). Operátor & vracia reťazec vytvorený zreťazením ľavého a pravého výrazu. Príklad: 'aaa' & 'bbb' vráti 'aaabbb'. Operátor je asociatívny a vyhodnocuje sa zľava doprava.
Unárne logické nie (!). Tento operátor vracia '1', ak je výraz False (vyhodnotí sa na prázdny reťazec), inak ''.
Logické a (&&). Tento operátor vracia ‚1‘, ak sú oba výrazy, ľavý aj pravý, True, alebo prázdny reťazec '', ak je niektorý False. Je asociatívny, vyhodnocuje sa zľava doprava a vykonáva skratové vyhodnocovanie.
Logické alebo (||). Tento operátor vracia '1', ak je ľavý alebo pravý výraz True, alebo '', ak sú oba False. Je asociatívny, vyhodnocuje sa zľava doprava a vykonáva skratové vyhodnocovanie. Ide o inkluzívne alebo, ktoré vracia '1', ak sú oba výrazy, ľavý aj pravý, True.

Odkazy na polia

field_reference sa vyhodnotí na hodnotu poľa metadát pomenovaného vyhľadávacím názvom, ktorý nasleduje za $ alebo $$. Použitie $ je ekvivalentné s použitím funkcie field. Použitie $$ je ekvivalentné s použitím funkcie raw_field. Príklady:

* $authors ==> field('authors')
* $#genre ==> field('#genre')
* $$pubdate ==> raw_field('pubdate')
* $$#my_int ==> raw_field('#my_int')

Výrazy If

Výrazy If najprv vyhodnotia podmienku. Ak je podmienka True (neprázdna hodnota), vyhodnotí sa expression_list v časti then. Ak je False, potom sa, ak je prítomný, vyhodnotí expression_list v časti elif alebo else. Časti elif a else sú voliteľné. Slová if, then, elif, else a fi sú vyhradené; nemôžete ich použiť ako názvy identifikátorov. Nové riadky a biele znaky môžete umiestniť všade, kde to dáva zmysel. Podmienka je top_expression, nie expression_list; bodkočiarky nie sú povolené. Expression_lists sú bodkočiarkami oddelené sekvencie top_expressions. Výraz if vracia výsledok posledného top_expression vo vyhodnotenom expression_list, alebo prázdny reťazec, ak sa nevyhodnotil žiadny zoznam výrazov.

Príklady:

* 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)

Príklad vnoreného if:

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

Ako bolo uvedené vyššie, if vytvára hodnotu. To znamená, že všetky nasledujúce sú ekvivalentné:

* 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

Napriklad tento program vracia hodnotu stĺpca series, ak kniha má sériu, inak hodnotu stĺpca title:

program: field(if field('series') then 'series' else 'title' fi)

Výrazy For

Výraz for iteruje cez zoznam hodnôt a spracúva ich jednu po druhej. List_expression sa musí vyhodnotiť buď na vyhľadávací názov poľa metadát, napr. tags alebo #genre, alebo na zoznam hodnôt. range generuje zoznam čísel. Ak je výsledkom platný vyhľadávací názov, načíta sa hodnota poľa a použije sa oddeľovač určený pre daný typ poľa. Ak výsledok nie je platný vyhľadávací názov, predpokladá sa, že ide o zoznam hodnôt. Predpokladá sa, že zoznam je oddelený čiarkami, pokiaľ nie je uvedené voliteľné kľúčové slovo separator, v ktorom prípade musia byť hodnoty zoznamu oddelené výsledkom vyhodnotenia separator_expr. Oddeľovač nemožno použiť, ak je zoznam generovaný pomocou range(). Každá hodnota v zozname sa priradí zadanej premennej a potom sa vyhodnotí expression_list. Na vyskočenie z cyklu môžete použiť break a na skok na začiatok cyklu pre ďalšiu iteráciu continue.

Príklad: Táto šablóna odstráni prvý hierarchický názov pre každú hodnotu v Genre (#genre) a vytvorí zoznam s novými názvami:

program:
  new_tags = '';
  for i in '#genre':
    j = re(i, '^.*?\.(.*)$', '\1');
    new_tags = list_union(new_tags, j, ',')
  rof;
  new_tags

Ak je pôvodný Genre History.Military, Science Fiction.Alternate History, ReadMe, šablóna vráti Military, Alternate History, ReadMe. Túto šablónu môžete použiť v calibre v Upraviť metadáta hromadne → Hľadať a nahradiť s Hľadať nastaveným na template na odstránenie prvej úrovne hierarchie a priradenie výslednej hodnoty do Genre.

Poznámka: posledný riadok v šablóne, new_tags, v tomto prípade nie je striktne potrebný, pretože for vracia hodnotu posledného top_expression v zozname výrazov. Hodnota priradenia je hodnota jeho výrazu, takže hodnota príkazu for je to, čo bolo priradené do new_tags.

Výrazy with

Výraz with:

zmení aktuálnu knihu na knihu s calibre id knihy (celé číslo) vytvoreným vyhodnotením top_expression.
spustí expression_list.
potom obnoví aktuálnu knihu na to, čím bola.

Výraz with vracia výsledok posledného top_expression vo vyhodnotenom expression_list, alebo prázdny reťazec, ak sa nevyhodnotil žiadny zoznam výrazov.

Napriklad táto šablóna vracia zoznam názvov všetkých kníh vybraných v GUI:

program:
  res = '';
  ids = selected_books();
  for id in ids:
      with id:
          res = (if res then res & ', ' fi) & $title
      htiw
  rof;
  res

Príkaz Return

Vráti hodnotu výrazu. Ak sa vykoná vo funkcii, vráti hodnotu výrazu volajúcemu. Ak sa vykoná v najvrchnejšom kontexte (šablóne), nastaví hodnotu šablóny na hodnotu výrazu a ukončí šablónu.

Definícia funkcie

Ak máte v šablóne opakujúci sa kód, môžete tento kód vložiť do lokálnej funkcie. Kľúčové slovo def začína definíciu. Nasleduje názov funkcie, zoznam argumentov a potom kód vo funkcii. Definícia funkcie končí kľúčovým slovom fed.

Argumenty sú pozičné. Pri volaní funkcie sa dodané argumenty priraďujú zľava doprava k definovaným parametrom, pričom hodnota argumentu sa priradí parametru. Je chybou poskytnúť viac argumentov, než je definovaných parametrov. Parametre môžu mať predvolené hodnoty, ako napríklad a = 25. Ak pre daný parameter nie je dodaný argument, použije sa predvolená hodnota, inak sa parameter nastaví na prázdny reťazec.

Príkaz return možno použiť v lokálnej funkcii.

Funkcia musí byť definovaná predtým, než sa použije.

Príklad: Táto šablóna vypočíta približné trvanie v rokoch, mesiacoch a dňoch z počtu dní. Funkcia to_plural() formátuje vypočítané hodnoty. Upozorňujeme, že príklad používa aj operátor &:

program:
      days = 2112;
      years = floor(days/360);
      months = floor(mod(days, 360)/30);
      days = days - ((years*360) + (months * 30));

      def to_plural(v, str):
              if v == 0 then return '' fi;
              return v & ' ' & (if v == 1 then str else str & 's' fi) & ' '
      fed;

      to_plural(years, 'year') & to_plural(months, 'month') & to_plural(days,'day')

Relačné operátory

Relačné operátory vracajú '1', ak je porovnanie pravdivé, inak prázdny reťazec ('').

Existujú dve formy relačných operátorov: porovnania reťazcov a číselné porovnania.

Porovnania reťazcov vykonávajú porovnanie reťazcov bez rozlišovania veľkosti písmen pomocou lexikálneho poradia. Podporované operátory porovnania reťazcov sú ==, !=, <, <=, >, >=, in, inlist a inlist_field. Pri operátoroch in, inlist a inlist_field sa výsledok ľavého výrazu interpretuje ako vzor regulárneho výrazu. Sú pravdivé, ak hodnota ľavého regulárneho výrazu zodpovedá hodnote pravého výrazu. Regulárne výrazy nerozlišujú veľkosť písmen.

Operátor inlist je pravdivý, ak ľavý regulárny výraz zodpovedá ktorejkoľvek položke v pravom zozname, kde sú položky v zozname oddelené čiarkami. Operátor inlist_field je pravdivý, ak ľavý regulárny výraz zodpovedá ktorejkoľvek položke v poli (stĺpci) pomenovanom pravým výrazom s použitím oddeľovača definovaného pre dané pole. Poznámka: operátor inlist_field vyžaduje, aby sa pravý výraz vyhodnotil na názov poľa, zatiaľ čo operátor inlist vyžaduje, aby sa pravý výraz vyhodnotil na reťazec obsahujúci zoznam oddelený čiarkami. Kvôli tomuto rozdielu je inlist_field podstatne rýchlejší než inlist, pretože sa nevykonávajú žiadne konverzie reťazcov ani konštrukcie zoznamov.

Číselné porovnávacie operátory sú ==#, !=#, <#, <=#, ># a >=#. Ľavý a pravý výraz sa musia vyhodnotiť na číselné hodnoty s dvomi výnimkami: reťazec „None“ (nedefinované pole) aj prázdny reťazec sa vyhodnotia na hodnotu nula.

Príklady:

program: field('series') == 'foo' vráti '1', ak je séria knihy foo, inak ''.

program: 'f.o' in field('series') vráti '1', ak séria knihy zodpovedá regulárnemu výrazu f.o (napr. foo, Off Onyx atď.), inak ''.

program: 'science' inlist $#genre vráti '1', ak niektorá z hodnôt získaných zo žánrov knihy zodpovedá regulárnemu výrazu science, napr. Science, History of Science, Science Fiction atď., inak ''.

program: '^science$' inlist $#genre vráti '1', ak niektorý zo žánrov knihy presne zodpovedá regulárnemu výrazu ^science$, napr. Science, inak ''. Žánre History of Science a Science Fiction nezodpovedajú.

program: 'asimov' inlist $authors vráti '1', ak niektorý autor zodpovedá regulárnemu výrazu asimov, napr. Asimov, Isaac alebo Isaac Asimov, inak ''.

program: 'asimov' inlist_field 'authors' vráti '1', ak niektorý autor zodpovedá regulárnemu výrazu asimov, napr. Asimov, Isaac alebo Isaac Asimov, inak ''.

program: 'asimov$' inlist_field 'authors' vráti '1', ak niektorý autor zodpovedá regulárnemu výrazu asimov$, napr. Isaac Asimov, inak ''. Nezodpovedá Asimov, Isaac kvôli kotve $ v regulárnom výraze.

program: if field('series') != 'foo' then 'bar' else 'mumble' fi vráti 'bar', ak séria knihy nie je foo. Inak vráti 'mumble'.

program: if field('series') == 'foo' || field('series') == '1632' then 'yes' else 'no' fi vráti 'yes', ak je séria buď foo, alebo 1632, inak 'no'.

program: if '^(foo|1632)$' in field('series') then 'yes' else 'no' fi vráti 'yes', ak je séria buď foo, alebo 1632, inak 'no'.

program: if 11 > 2 then 'yes' else 'no' fi vráti 'no', pretože operátor > vykonáva lexikálne porovnanie.

program: if 11 ># 2 then 'yes' else 'no' fi vráti 'yes', pretože operátor ># vykonáva číselné porovnanie.

Funkcie vo všeobecnom programovom režime

Zoznam funkcií zabudovaných v jazyku šablón nájdete v Príručka funkcií šablóny.

Poznámky:

Na rozdiel od režimu jednej funkcie musíte vo všeobecnom programovom režime uviesť prvý parameter value.
Všetky parametre sú expression_lists (pozri gramatiku vyššie).

Zložitejšie programy vo výrazoch šablóny – režim programu šablóny¶

Režim programu šablóny (TPM) je kombináciou všeobecného programového režimu a režimu jednej funkcie. TPM sa líši od režimu jednej funkcie tým, že umožňuje písať výrazy šablóny, ktoré odkazujú na iné polia metadát, používajú vnorené funkcie, upravujú premenné a vykonávajú aritmetiku. Líši sa od všeobecného programového režimu tým, že šablóna je uzavretá medzi znakmi { a } a nezačína slovom program:. Programová časť šablóny je zoznam výrazov všeobecného programového režimu.

Príklad: predpokladajme, že chcete, aby šablóna zobrazila sériu knihy, ak ju má, inak hodnotu vlastného poľa #genre. V režime jednej funkcie to nemôžete urobiť, pretože vo výraze šablóny nemôžete odkazovať na iné pole metadát. V TPM môžete, ako ukazuje nasledujúci výraz:

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

Príklad ukazuje niekoľko vecí:

TPM sa použije, ak výraz začína :' a končí '}. Všetko ostatné sa považuje za režim jednej funkcie.

Ak šablóna obsahuje predponu a príponu, výraz končí '|, kde | je oddeľovač pre predponu. Príklad:
```
{series:'ifempty($, $#genre)'|prefix | suffix}
```
Funkciám musia byť dané všetky ich argumenty. Napríklad štandardným vstavaným funkciám musí byť daný počiatočný parameter value.
Premennú $ možno použiť ako argument value a predstavuje hodnotu poľa pomenovaného v šablóne, v tomto prípade series.
Biele znaky sa ignorujú a možno ich použiť kdekoľvek vo výraze.
konštantné reťazce sú uzavreté v zodpovedajúcich úvodzovkách, buď ' alebo ".

V TPM môže používanie znakov { a } v reťazcových literáloch viesť k chybám alebo neočakávaným výsledkom, pretože mätú procesor šablón. Ten sa ich snaží považovať za hranice výrazov šablóny, nie za znaky. V niektorých, ale nie všetkých prípadoch môžete nahradiť { za [[ a } za ]]. Rada: ak váš program obsahuje znaky { a }, mali by ste použiť všeobecný programový režim.

Režim šablóny Python¶

Režim šablóny Python (PTM) vám umožňuje písať šablóny pomocou natívneho Pythonu a API calibre. Najviac sa využije databázové API; ďalšia diskusia presahuje rozsah tejto príručky. Šablóny PTM sú rýchlejšie a dokážu vykonávať zložitejšie operácie, ale musíte vedieť písať kód v Pythone s použitím API calibre.

Šablóna PTM začína:

python:
def evaluate(book, context):
    # book is a calibre metadata object
    # context is an instance of calibre.utils.formatter.PythonTemplateContext,
    # which currently contains the following attributes:
    # db: a calibre legacy database object.
    # globals: the template global variable dictionary.
    # arguments: is a list of arguments if the template is called by a GPM template, otherwise None.
    # funcs: used to call Built-in/User functions and Stored GPM/Python templates.
    # Example: context.funcs.list_re_group()

    # your Python code goes here
    return 'a string'

Vyššie uvedený text môžete do šablóny pridať pomocou kontextovej ponuky, zvyčajne prístupnej kliknutím pravým tlačidlom myši. Komentáre nie sú podstatné a možno ich odstrániť. Musíte použiť odsadenie Pythonu.

Objekt kontextu podporuje str(context), ktorý vracia reťazec obsahu kontextu, a context.attributes, ktorý vracia zoznam názvov atribútov v kontexte.

Atribút context.funcs umožňuje volať vstavané a používateľské funkcie šablóny a uložené šablóny GPM/Python, takže ich môžete spúšťať priamo vo svojom kóde. Funkcie sa získavajú pomocou ich názvov. Ak názov koliduje s kľúčovým slovom Pythonu, pridajte na koniec názvu podčiarknik. Príklady:

context.funcs.list_re_group()
context.funcs.assert_()

Tu je príklad šablóny PTM, ktorá vytvára zoznam všetkých autorov pre sériu. Zoznam je uložený v stĺpci vytvorenom z iných stĺpcov, správa sa ako značky. Zobrazuje sa v Podrobnostiach o knihe a má začiarknuté na samostatných riadkoch (v Nastavenia → Vzhľad a chovanie → Podrobnosti o knihe). Táto možnosť vyžaduje, aby bol zoznam oddelený čiarkami. Aby sa splnila táto požiadavka, šablóna konvertuje čiarky v menách autorov na bodkočiarky a potom vytvorí zoznam autorov oddelený čiarkami. Autori sa potom zoradia, preto šablóna používa author_sort.

python:
def evaluate(book, context):
    if book.series is None:
        return ''
    db = context.db.new_api
    ans = set()
    # Get the list of books in the series
    ids = db.search(f'series:"={book.series}"', '')
    if ids:
        # Get all the author_sort values for the books in the series
        author_sorts = (v for v in db.all_field_for('author_sort', ids).values())
        # Add the names to the result set, removing duplicates
        for aus in author_sorts:
            ans.update(v.strip() for v in aus.split('&'))
    # Make a sorted comma-separated string from the result set
    return ', '.join(v.replace(',', ';') for v in sorted(ans))

Výstup v Podrobnostiach o knihe vyzerá takto:

Šablóny a URL adresy¶

Šablóny môžete použiť na vytváranie URL adries. Tu sú opísané dva prípady:

Vyhľadávacie URL adresy vlastného stĺpca v Podrobnostiach o knihe
Schéma URL calibre

Vyhľadávacie URL adresy vlastného stĺpca v podrobnostiach o knihe

Pri vytváraní vlastného stĺpca môžete pomocou šablóny poskytnúť URL adresu, ktorá sa použije v Podrobnostiach o knihe. Napríklad, ak máte vlastný stĺpec pre Translators, môžete definovať URL adresu, ktorá vás zavedie na stránku pre prekladateľov. Vyhľadávacie URL adresy v podrobnostiach o knihe možno poskytnúť pre typy stĺpcov Text, Enumerated, Series a Column built from other column.

Keď sa v Podrobnostiach o knihe klikne na položku s vyhľadávacou šablónou, šablóna sa vyhodnotí. Poskytnú sa jej bežné metadáta knihy. Poskytnú sa jej tiež tri dodatočné polia:

item_value: hodnota kliknutej položky.
item_value_quoted: hodnota kliknutej položky, URL-kódovaná. Špeciálne znaky sú escapované, aby boli platné v URL adresách, a medzery sú nahradené znakmi '+' (plus).
item_value_no_plus: hodnota kliknutej položky, URL-kódovaná. Špeciálne znaky sú escapované, aby boli platné v URL adresách, a medzery sú nahradené %20, nie plus.

Existuje niekoľko spôsobov, ako vytvoriť URL adresu. Nasledujúce používa Wikipédiu ako príklad.

Najjednoduchšia je základná šablóna:

https://en.wikipedia.org/w/index.php?search={item_value_encoded}

V niektorých prípadoch môžete chcieť vykonať viac spracovania. V závislosti od zložitosti spracovania môžete použiť štyri funkcie šablóny.

make_url(path, [query_name, query_value]+) – táto funkcia je najjednoduchší spôsob zostavenia dotazovacej URL. Používa path, webovú stránku, ktorú chcete dotazovať, a dvojice query_name, query_value, z ktorých sa dotaz vytvorí. Vo všeobecnosti musí byť query_value zakódovaná pre URL. Pri tejto funkcii je vždy zakódovaná a medzery sa vždy nahrádzajú znakmi '+'.
make_url_extended(...) – táto funkcia je podobná funkcii make_url(), ale poskytuje väčšiu kontrolu nad komponentmi URL. Komponenty URL sú

scheme:://authority/path?query string.

Podrobnejšie informácie nájdete na Uniform Resource Locator na Wikipédii.

Funkcia má dva varianty:
```
make_url_extended(scheme, authority, path, [query_name, query_value]+)
```
a
```
make_url_extended(scheme, authority, path, query_string)
```
query_string([query_name, query_value, how_to_encode]+)– vráti dotazovací reťazec URL zostavený z trojíc query_name, query_value, how_to_encode. Dotazovací reťazec je séria položiek, kde každá položka vyzerá ako query_name=query_value, pričom query_value je zakódovaná pre URL podľa pokynu. Dotazovacie položky sú oddelené znakmi '&' (ampersand).
encode_for_url(value, use_plus) – vráti value zakódovanú na použitie v URL podľa use_plus. Hodnota sa najprv zakóduje pre URL. Potom, ak je use_plus 0, medzery sa nahradia znakmi '+' (plus). Ak je 1, medzery sa nahradia %20.

Napriklad predpokladajme, že máte vlastný stĺpec Translators (#translators), kde sú mená v tvare Priezvisko, Krstné meno. Pri vytváraní URL adresy možno budete musieť previesť meno na Krstné meno Priezvisko. Na tento účel môžete použiť funkciu make_url:

program: make_url('https://en.wikipedia.org/w/index.php', 'search', swap_around_comma($item_value))

Ak predpokladáme, že meno prekladateľa je Boy-Żeleński, Tadeusz, vyššie uvedená šablóna vytvorí odkaz:

https://en.wikipedia.org/w/index.php?search=Tadeusz+Boy-%C5%BBele%C5%84ski

Upozorňujeme, že krstné meno osoby je teraz prvé, medzera je teraz plus a inojazyčné znaky v priezvisku sú URL-kódované.

Funkcie make_url_extended, query_string a encode_for_url môžu byť užitočné v závislosti od dodatočnej zložitosti spracovania.

Schéma URL calibre

Calibre podporuje niekoľko rôznych URL adries na navigáciu v knižniciach calibre. Táto sekcia ukazuje, ako používať šablóny na vytváranie niektorých URL adries. Podrobnosti o dostupných URL adresách nájdete v Schéma URL calibre://.

Prepnúť na konkrétnu knižnicu. Syntax tejto URL adresy je:
```
calibre://switch-library/Library_Name
```
Library_Name treba nahradiť názvom knižnice calibre, ktorú chcete otvoriť. Názov knižnice sa zobrazuje v záhlaví okna. Je to jednoduchý názov, nie cesta k súboru knižnice. Musíte ho napísať tak, ako sa zobrazuje v záhlaví, vrátane veľkosti písmen. Znak _ (podčiarknik) predstavuje aktuálnu knižnicu. Ak názov obsahuje medzery alebo špeciálne znaky, musí byť hexadecimálne kódovaný pomocou funkcie to_hex, ako v nasledujúcom príklade:
```
program: strcat('calibre://switch-library/_hex_-', to_hex(current_library_name()))
```
Šablóna vytvorí URL adresu:
```
calibre://switch-library/_hex_-4c6962726172792e746573745f736d616c6c
```
Funkciu current_library_name() môžete nahradiť skutočným názvom knižnice, ako v:
```
program: strcat('calibre://switch-library/_hex_-', to_hex('Library.test_small'))
```
Odkazy na zobrazenie kníh. Tieto odkazy vyberú knihu v knižnici calibre. Syntax tejto URL adresy je:
```
calibre://show-book/Library_Name/book_id
```
book id je číselné calibre id knihy, dostupné šablónam ako $id. Ako vyššie, názov knižnice môže byť potrebné hexadecimálne kódovať. Tu je príklad:
```
program: strcat('calibre://show-book/_hex_-', to_hex(current_library_name()), '/', $id)
```
Vytvorí URL adresu:
```
calibre://show-book/_hex_-4c6962726172792e746573745f736d616c6c/1353
```
Vyhľadávanie kníh. Tieto odkazy vyhľadávajú knihy v zadanej knižnici calibre. Syntax tejto URL adresy je:
```
calibre://search/Library_Name?q=query
calibre://search/Library_Name?eq=hex_encoded_query
```
kde query je akýkoľvek platný vyhľadávací výraz calibre. Každý dopyt obsahujúci medzery alebo špeciálne znaky musíte hexadecimálne kódovať, čo vo všeobecnosti znamená všetky. Napríklad vyhľadávací výraz calibre na vyhľadávanie hierarchickej značky začínajúcej na „AA“ je tags:"=.AA". Táto šablóna vytvorí vyhľadávaciu URL adresu pre tento výraz:
```
program: strcat('calibre://search/_hex_-', to_hex(current_library_name()), '?eq=', to_hex('tags:"=.AA"'))
```
Výsledná URL adresa je:
```
calibre://search/_hex_-4c6962726172792e746573745f736d616c6c?eq=746167733a223d2e414122
```
Tu je príklad tej istej URL adresy vytvorenej pomocou funkcie :ref:ff_make_url_extended namiesto strcat:
```
program: make_url_extended('calibre', '', 'search/_hex_-' & to_hex(current_library_name()),
                           'eq', to_hex('tags:"=.AA"'))
```

Otvoriť okno s podrobnosťami o knihe pre knihu v niektorej knižnici. Syntax tejto URL adresy je:

calibre://book-details/Library_Name/book_id

Príklad šablóny je:

program: strcat('calibre://book-details/_hex_-', to_hex(current_library_name()), '/', $id)

ktorá vytvorí URL adresu:

calibre://book-details/_hex_-4c6962726172792e746573745f736d616c6c/1353

Otvoriť poznámky priradené k autorovi/sérii atď. Syntax URL adresy je:
```
calibre://book-details/Library_Name/Field_Name/id_Item_Id
calibre://book-details/Library_Name/Field_Name/hex_Hex_Encoded_Item_Name
```
Field_Name je vyhľadávací názov poľa. Ak je pole vlastný stĺpec, nahraďte znak # podčiarknikom (_). Item_Id je interné číselné ID hodnoty v poli. Neexistuje funkcia šablóny, ktorá by vracala Item_Id, takže šablóny zvyčajne používajú druhú formu, Hex_Encoded_Item_Name. Tu je ukážková šablóna, ktorá otvorí poznámku pre osobu Boy-Żeleński, Tadeusz v poli #authtest:
```
program: strcat('calibre://show-note/_hex_-', to_hex(current_library_name()),
                '/_authtest/hex_', to_hex('Boy-Żeleński, Tadeusz'))
```
ktorá vytvorí URL adresu:
```
calibre://show-note/_hex_-4c6962726172792e746573745f736d616c6c/_authtest/hex_426f792dc5bb656c65c584736b692c205461646575737a
```

Uložené šablóny¶

Aj všeobecný programový režim, aj režim šablóny Python podporujú ukladanie šablón a volanie týchto šablón z inej šablóny, podobne ako volanie uložených funkcií. Šablóny ukladáte cez Nastavenia → Pokročilé → Funkcie šablóny. Viac informácií poskytuje toto dialógové okno. Šablónu voláte rovnako ako funkciu, pričom voliteľne odovzdávate pozičné argumenty. Argumentom môže byť akýkoľvek výraz. Príklady volania šablóny, za predpokladu, že uložená šablóna sa nazýva foo:

foo() – volanie šablóny bez argumentov.
foo(a, b) volanie šablóny s hodnotami dvoch premenných a a b.
foo(if field('series') then field('series_index') else 0 fi) – ak má kniha series, odovzdá sa series_index, inak sa odovzdá hodnota 0.

V GPM získate argumenty odovzdané pri volaní uloženej šablóny pomocou funkcie arguments. Tá deklaruje a inicializuje lokálne premenné, teda parametre. Premenné sú pozičné; získajú hodnotu parametra uvedeného pri volaní na rovnakej pozícii. Ak príslušný parameter nie je pri volaní uvedený, funkcia arguments priradí tejto premennej uvedenú predvolenú hodnotu. Ak neexistuje predvolená hodnota, premenná sa nastaví na prázdny reťazec. Napríklad nasledujúca funkcia arguments deklaruje 2 premenné, key a alternate:

arguments(key, alternate='series')

Príklady, opäť za predpokladu, že uložená šablóna sa nazýva foo:

foo('#myseries') – argumentu key sa priradí hodnota 'myseries' a argumentu alternate sa priradí predvolená hodnota 'series'.
foo('series', '#genre') – premennej key sa priradí hodnota 'series' a premennej alternate sa priradí hodnota '#genre'.
foo() – premennej key sa priradí prázdny reťazec a premennej alternate sa priradí hodnota 'series'.

V PTM sa argumenty odovzdávajú v parametri arguments, čo je zoznam reťazcov. Neexistuje spôsob, ako určiť predvolené hodnoty. Musíte skontrolovať dĺžku zoznamu arguments, aby ste sa uistili, že počet argumentov je taký, ako očakávate.

Jednoduchým spôsobom testovania uložených šablón je dialógové okno Testovač šablón. Pre jednoduchší prístup mu priraďte klávesovú skratku v Nastavenia → Pokročilé → Klávesové skratky → Testovač šablón. Priradenie skratky dialógovému oknu Uložené šablóny pomôže rýchlejšie prepínať medzi testovačom a úpravou zdrojového kódu uloženej šablóny.

Poskytovanie dodatočných informácií šablónam¶

Vývojár sa môže rozhodnúť odovzdať procesoru šablón dodatočné informácie, ako sú metadáta knihy špecifické pre aplikáciu alebo informácie o tom, čo sa od procesora žiada. Šablóna môže k týmto informáciám pristupovať a použiť ich počas vyhodnocovania.

Vývojár: ako odovzdať dodatočné informácie

Dodatočné informácie sú slovník Pythonu obsahujúci páry variable_name: variable_value, kde hodnoty musia byť reťazce. Šablóna môže k slovníku pristupovať a vytvárať lokálne premenné šablóny s názvom variable_name obsahujúce hodnotu variable_value. Používateľ nemôže názov zmeniť, preto je najlepšie používať názvy, ktoré nebudú kolidovať s inými lokálnymi premennými šablóny, napríklad pridaním podčiarknika na začiatok názvu.

Tento slovník sa odovzdáva procesoru šablón (formatter) pomocou pomenovaného parametra global_vars=your_dict. Úplná signatúra metódy je:

def safe_format(self, fmt, kwargs, error_value, book,
                column_name=None, template_cache=None,
                strip_results=True, template_functions=None,
                global_vars={})

Autor šablóny: ako pristupovať k dodatočným informáciám

K dodatočným informáciám (slovníku globals) pristupujete v šablóne pomocou funkcie šablóny:

globals(id[=expression] [, id[=expression]]*)

kde id je akýkoľvek platný názov premennej. Táto funkcia skontroluje, či dodatočné informácie poskytnuté vývojárom obsahujú tento názov. Ak áno, funkcia priradí poskytnutú hodnotu lokálnej premennej šablóny s týmto názvom. Ak názov nie je v dodatočných informáciách a je poskytnutý výraz, výraz sa vyhodnotí a výsledok sa priradí lokálnej premennej. Ak nie je poskytnutá ani hodnota, ani výraz, funkcia priradí lokálnej premennej prázdny reťazec ('').

Šablóna môže nastaviť hodnotu v slovníku globals pomocou funkcie šablóny:

set_globals(id[=expression] [, id[=expression]]*)

Táto funkcia nastaví pár kľúč:hodnota id:value v slovníku globals, kde value je hodnota lokálnej premennej šablóny id. Ak táto lokálna premenná neexistuje, value sa nastaví na výsledok vyhodnotenia výrazu.

Poznámky k rozdielom medzi režimami¶

Tri programové režimy, režim jednej funkcie (SFM), režim programu šablóny (TPM) a všeobecný programový režim (GPM), fungujú odlišne. SFM je určený na to, aby bol „jednoduchý“, takže skrýva veľa častí programovacieho jazyka.

Rozdiely:

V SFM sa hodnota stĺpca vždy odovzdáva ako „neviditeľný“ prvý argument funkcii zahrnutej v šablóne.
SFM nepodporuje rozdiel medzi premennými a reťazcami; všetky hodnoty sú reťazce.
Nasledujúca šablóna SFM vracia buď názov série, alebo reťazec „no series“:
```
{series:ifempty(no series)}
```
Ekvivalentná šablóna v TPM je
```
{series:'ifempty($, 'no series')'}
```
Ekvivalentná šablóna v GPM je:
```
program: ifempty(field('series'), 'no series')
```
Prvým argumentom funkcie ifempty je hodnota poľa series. Druhým argumentom je reťazec no series. V SFM sa prvý argument, hodnota poľa, odovzdáva automaticky (neviditeľný argument).
Niekoľko funkcií šablóny, napríklad booksize() a current_library_name(), neprijíma žiadne argumenty. Kvôli „neviditeľnému argumentu“ nemôžete tieto funkcie v SFM použiť.
Vnorené funkcie, kde funkcia volá inú funkciu na výpočet argumentu, nemožno v SFM použiť. Napríklad táto šablóna, ktorá má vrátiť prvých 5 znakov hodnoty série veľkými písmenami, nebude v SFM fungovať:
```
{series:uppercase(substr(0,5))}
```

TPM a GPM podporujú vnorené funkcie. Vyššie uvedená šablóna v TPM by bola:

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

V GPM by bola:

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

Ako je uvedené v sekcii režim programu šablóny vyššie, používanie znakov { a } v reťazcových literáloch TPM môže viesť k chybám alebo neočakávaným výsledkom, pretože mätú procesor šablón. Ten sa ich snaží považovať za hranice šablóny, nie za znaky. V niektorých, ale nie všetkých prípadoch môžete nahradiť { za [[ a } za ]]. Vo všeobecnosti, ak váš program obsahuje znaky { a }, mali by ste použiť všeobecný programový režim.

Používateľom definované funkcie šablóny Python¶

Do procesora šablón môžete pridať svoje vlastné funkcie Pythonu. Takéto funkcie možno použiť v ktoromkoľvek z troch režimov programovania šablón. Funkcie sa pridávajú cez Nastavenia → Pokročilé → Funkcie šablóny. Pokyny sú uvedené v tomto dialógovom okne. Upozorňujeme, že na podobný účel môžete použiť šablóny Python. Keďže volanie používateľom definovaných funkcií je rýchlejšie než volanie šablóny Python, používateľom definované funkcie môžu byť efektívnejšie v závislosti od zložitosti toho, čo funkcia alebo šablóna robí.

Špeciálne poznámky k používaniu šablón v rôznych kontextoch¶

V GUI (Stĺpce vytvorené z iných stĺpcov a Vyhľadávania šablón):

Šablóny GPM fungujú ako predtým.
Šablóny Python majú plný prístup k databáze calibre.

V pravidlách pre ikony:

šablóny pravidiel pre ikony nemajú údaje o knihe, takže funkcie založené na poliach, ako napríklad format_date_field, list_count_field a check_yes_no, nebudú fungovať.

V serveri obsahu:

Šablóny majú prístup k novému API, ale nie k starému API (LibraryDatabase).
Z vyššie uvedeného dôvodu nie je zaručené, že nasledujúce funkcie formátovača budú fungovať v šablónach GPM (zložené stĺpce, pravidlá pre ikony atď.), a mali by ste sa im vyhnúť, ak používate server obsahu:

Špeciálne poznámky k šablónam ukladania a odosielania¶

Špeciálne spracovanie sa použije, keď sa šablóna použije v šablóne Uložiť na disk alebo Poslať do zariadenia. Hodnoty polí sa vyčistia a znaky špeciálne pre súborové systémy sa nahradia podčiarknikmi, vrátane lomítok. To znamená, že text poľa nemožno použiť na vytváranie priečinkov. Lomítka sa však nemenia v reťazcoch predpony alebo prípony, takže lomítka v týchto reťazcoch spôsobia vytvorenie priečinkov. Vďaka tomu môžete vytvoriť štruktúru priečinkov s premenlivou hĺbkou.

Napriklad predpokladajme, že chceme štruktúru priečinkov series/series_index - title, s tým, že ak séria neexistuje, názov by mal byť v najvyššom priečinku. Šablóna na to je:

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

Lomítko a spojovník sa zobrazia iba vtedy, ak séria nie je prázdna.

Funkcia lookup nám umožňuje ešte efektnejšie spracovanie. Napríklad predpokladajme, že ak má kniha sériu, chceme štruktúru priečinkov series/series index - title.fmt. Ak kniha nemá sériu, chceme štruktúru priečinkov genre/author_sort/title.fmt. Ak kniha nemá žáner, chceme použiť „Unknown“. Chceme dve úplne odlišné cesty v závislosti od hodnoty série.

Aby sme to dosiahli, vykonáme:

Vytvorte zložené pole (s vyhľadávacím názvom #aa) obsahujúce {series}/{series_index} - {title}. Ak séria nie je prázdna, táto šablóna vytvorí series/series_index - title.
Vytvorte zložené pole (s vyhľadávacím názvom #bb) obsahujúce {#genre:ifempty(Unknown)}/{author_sort}/{title}. Táto šablóna vytvorí genre/author_sort/title, kde prázdny žáner je nahradený Unknown.
Nastavte šablónu ukladania na {series:lookup(.,#aa,#bb)}. Táto šablóna vyberie zložené pole #aa, ak séria nie je prázdna, a zložené pole #bb, ak je séria prázdna. Máme teda dve úplne odlišné cesty ukladania v závislosti od toho, či je series prázdna alebo nie.

Tipy¶

Na testovanie šablón použite Testovač šablón. Pridajte testovač do kontextovej ponuky pre knihy v knižnici alebo mu priraďte klávesovú skratku.
Šablóny môžu používať iné šablóny odkazovaním na zložené stĺpce vytvorené s požadovanou šablónou. Prípadne môžete použiť uložené šablóny.
V plugboarde môžete nastaviť pole na prázdne (alebo čokoľvek, čo je ekvivalentné prázdnemu) pomocou špeciálnej šablóny {}. Táto šablóna sa vždy vyhodnotí na prázdny reťazec.
Vyššie opísaná technika na zobrazenie čísel, aj keď majú nulovú hodnotu, funguje so štandardným poľom series_index.

Príručka funkcií šablóny¶

Reference for all built-in template language functions