Le langage de modèle calibre¶

Le langage de modèle de calibre est un langage spécifique à calibre utilisé dans l’ensemble de calibre pour des tâches telles que la spécification des chemins de fichiers, le formatage des valeurs et le calcul de la valeur des colonnes spécifiées par l’utilisateur. Exemples :

Spécifier la structure du dossier et les noms de fichiers lors de l’enregistrement des fichiers de la bibliothèque calibre sur le disque ou le lecteur de livres numériques.
Définir des règles pour l’ajout d’icônes et de couleurs à la liste de livres de calibre.
Définir les colonnes virtuelles qui contiennent des données provenant d’autres colonnes.
Recherche avancée dans la bibliothèque.
Recherche et remplacement avancé des métadonnées.

Le langage est construit autour de la notion de modèle, qui spécifie les métadonnées du livre à utiliser, les calculs sur ces métadonnées, et la façon dont elles doivent être formatées.

Modèles de base¶

Un modèle de base est constitué d’une ou plusieurs expression modèle. Une expression modèle consiste en du texte et des noms entre crochets ({}) qui sont remplacés par les métadonnées correspondantes du livre en cours de traitement. Par exemple, le modèle par défaut de calibre utilisé pour enregistrer des livres sur un périphérique comporte 4 expressions modèle:

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

Pour le livre « The Foundation » par « Isaac Asimov » cela donnera:

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

Les barres obliques ne sont pas des expressions modèle car elles se trouvent entre les {}. Un tel texte est laissé là où il apparaît. Par exemple, si le modèle est:

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

dès lors, pour « The Foundation », le modèle produit:

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

Une expression modèle peut accéder à toutes les métadonnées disponibles dans calibre, y compris les colonnes personnalisées (colonnes que vous créez vous-même), en utilisant le nom de recherche d’une colonne. Pour trouver le nom de recherche d’une colonne (parfois appelée champs), passez votre souris sur l’en-tête de la colonne dans la liste des livres de calibre. Les noms de recherche pour les colonnes personnalisées commencent toujours par #. Pour les colonnes de type série, il y a un champ supplémentaire appelé #lookup name_index qui est l’index de la série pour ce livre dans la série. Par exemple, si vous avez une colonne de série personnalisée nommée #messéries, il y aura également une colonne nommée #messéries_index. L’index de la colonne de série standard est nommé series_index.

En plus des champs standard basés sur des colonnes, vous pouvez également utiliser :

{formats} - Une liste des formats disponibles dans la bibliothèque calibre pour un livre

{identifiers:select(isbn)} - L’ISBN du livre

Si les métadonnées du champ pour un livre donné ne sont pas définies, le champ dans le modèle est remplacé par la chaîne vide (''). Par exemple, considérons le modèle suivant

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

Si le livre d’Asimov « Seconde Fondation » fait partie de la série « Fondation », alors le modèle produit

Asimov, Isaac/Foundation/Second Foundation 3

Si aucune série n’a été saisie pour le livre, le modèle produit

Asimov, Isaac/Second Foundation

Le processeur de modèles supprime automatiquement les barres obliques multiples et les espaces avant ou arrière.

Mise en forme avancée¶

Outre la substitution de métadonnées, les modèles peuvent inclure du texte supplémentaire de manière conditionnelle et contrôler le formatage des données substituées.

Comprenant conditionnellement le texte

Parfois, vous voulez que du texte n’apparaisse dans la sortie que si un champ n’est pas vide. Un cas courant est celui de series et series_index où vous voulez soit rien, soit les deux valeurs séparées par un trait d’union. calibre gère ce cas en utilisant une syntaxe spéciale de expression modèle.

Par exemple, et en utilisant l’exemple de Fondation ci-dessus, supposons que vous voulez que le modèle produise Fondation - 3 - Deuxième Fondation. Ce modèle produit ce résultat :

{series} - {series_index} - {title}

Cependant, si un livre n’a pas de série, le modèle produira - - le titre, ce qui n’est probablement pas ce que vous voulez. En général, les gens veulent que le résultat soit le titre sans les traits d’union superflus. Vous pouvez y parvenir en utilisant la syntaxe de modèle suivante :

{field:|prefix_text|suffix_text}

Cette expression modèle indique que si champ a la valeur XXXX, le résultat sera prefix_textXXXXXsuffix_text. Si champ est vide (n’a pas de valeur) alors le résultat sera la chaîne vide (rien) car le préfixe et le suffixe sont ignorés. Le préfixe et le suffixe peuvent contenir des blancs.

Ne pas utiliser de sous-modèles (`{ … }`) ou de fonctions (voir ci-dessous) dans le préfixe ou le suffixe.

En utilisant cette syntaxe, nous pouvons résoudre le problème de non-série ci-dessus avec le modèle

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

Les traits d’union ne seront inclus que si le livre possède un index de série, ce qui n’est le cas que si le livre possède une série. Si l’on reprend l’exemple de Fondation, le modèle produira Fondation - 1 - Deuxième Fondation.

Notes :

Vous devez inclure les deux points après le nom de la recherche si vous utilisez un préfixe ou un suffixe.
Vous devez utiliser soit aucun des caractères |, soit les deux. L’utilisation d’un seul caractère, comme dans {field:| - }, n’est pas autorisée.
Il est possible de ne fournir aucun texte pour le préfixe ou le suffixe, comme dans {série:|| - }. Le modèle {title:||} est le même que {title}.

Formatage

Supposons que vous vouliez que series_index soit formaté en trois chiffres avec des zéros en tête. Ceci fait l’affaire :

{series_index:0>3s} - Trois chiffres avec des zéros en tête

Pour des zéros qui suivent, utilisez:

{series_index:0>3s} - Trois chiffres avec des zéros qui suivent

Si vous utilisez des indices de série avec des valeurs fractionnées, par exemple 1.1, vous pouvez souhaiter que les points décimaux soient alignés. Par exemple, vous pouvez vouloir que les indices 1 et 2.5 apparaissent sous la forme 01.00 et 02.50 afin qu’ils soient triés correctement sur un périphérique qui effectue un tri lexical. Pour ce faire, utilisez :

{series_index:0>5.2f} - Cinq caractères composés de deux chiffres avec des zéros en tête, un point décimal, puis deux chiffres après le point décimal.

Si vous ne voulez que les deux premières lettres de la donnée, utilisez :

{author_sort :.2} - Seulement les deux premières lettres du nom de tri de l’auteur

Une grande partie du formatage du langage de modèle de calibre provient de Python. Pour plus de détails sur la syntaxe de ces opérations de formatage avancées, voir la documentation Python <https://docs.python.org/3/library/string.html#formatstrings>

Utilisation de modèles pour définir des colonnes personnalisées¶

Les modèles peuvent être utilisés pour afficher des informations qui ne sont pas dans les métadonnées de calibre, ou pour afficher les métadonnées différemment du format normal de calibre. Par exemple, vous pourriez vouloir afficher le ISBN, un champ que calibre n’affiche pas. Pour cela, vous pouvez créer une colonne personnalisée de type Colonne construite à partir d’autres colonnes (appelée ci-après colonnes composites) et fournir un modèle pour générer le texte affiché. La colonne affichera le résultat de l’évaluation du modèle. Par exemple, pour afficher l’ISBN, créez la colonne et entrez « identifiers:select(isbn)} » dans la champ du modèle. Pour afficher une colonne contenant les valeurs de deux colonnes personnalisées de séries, séparées par une virgule, utilisez {#series1:||,}{#series2}.

Les colonnes composites peuvent utiliser n’importe quelle option modèle, y compris le formatage.

Remarque : Vous ne pouvez pas modifier les données affichées dans une colonne composite. Vous devez plutôt modifier les colonnes sources. Si vous modifiez une colonne composite, par exemple en double-cliquant dessus, calibre ouvrira le modèle à modifier, et non les données sous-jacentes.

Modèles et tableaux de connexions¶

Les tableaux de connexions sont utilisés pour modifier les métadonnées écrites dans les livres pendant l’envoi à une liseuse et les opérations de sauvegarde sur le disque. Le tableau de connexion vous permet de spécifier pour un modèle de lecteur précis quelles données à insérer dans les métadonnées du livre. Vous pouvez utiliser les tableaux de connexions pour modifier les champs suivants : authors, author_sort, language, publisher, tags, title, title_sort. Cette fonctionnalité aide ceux qui veulent utiliser les différentes métadonnées des livres pour contrôler le tri ou l’affichage des livres sur leurs périphériques.

Lorsque vous créez un tableau de connexion, vous spécifiez le format et le périphérique pour lequel le tableau de connexion doit être utilisé. Un périphérique spécial est procuré, save_to_disk qui est utilisé lors de la sauvegarde de formats (en opposition à les envoyer vers le périphérique). Une fois que vous avez choisi le format et le périphérique, vous choisissez les champs de métadonnées à modifier, indiquez le modèle à appliquer pour fournir les nouvelles valeurs. Ces modèles sont reliés à leurs champs de destination, d’où le nom de tableau de connexions. Vous pouvez bien sûr utiliser des colonnes composites dans ces modèles.

Les tableaux de connexions sont assez flexibles et peuvent être écrits en mode fonction unique, en mode programme modèle, en mode programme général ou en mode modèle Python.

Quand un tableau de connexion doit s’appliquer (Serveur de contenu, sauvegarde sur disque ou envoyer au périphérique), calibre recherche les tableau de connexions définis et celui qui est correct pour le format donné et le périphérique. Par exemple, pour trouver le tableau de connexion approprié pour un livre EPUB envoyé à un périphérique ANDROID, calibre recherche dans les tableaux de connexion dans l’ordre de recherche suivant :

un tableau de connexion avec une correspondance exacte sur le format et le périphérique, par ex., EPUB et ANDROID
un tableau de connexion avec une correspondance exacte sur le format et le choix spécial n'importe quel périphérique, par ex., EPUB et n'importe quel périphérique
un tableau de connexion avec le choix spécial n'importe quel format et une correspondance exacte sur le périphérique, par ex., n'importe quel format et ANDROID
un tableau de conversion avec n'importe quel format et n'importe quel périphérique

Les étiquettes et les champs auteur ont un traitement spécial, parce que ces deux champs peuvent contenir plusieurs données. Un livre peut avoir plusieurs étiquettes et plusieurs auteurs. Lorsque vous spécifiez que l’un de ces deux champs doit être modifié, le résultat du modèle est examiné pour voir s’il y a plus d’un élément dedans. Pour les étiquettes, le résultat est découpé partout où calibre trouve une virgule. Par exemple, si le modèle produit les valeurs Thriller, Horreur, alors ke résultat sera deux étiquettes, Thriller et Horreur. Il n’est pas possible de mettre une virgule au milieu d’une étiquette.

La même chose se produit pour les auteurs, mais en utilisant un caractère différent comme séparateur, le & (esperluette) au lieu d’une virgule. Par exemple, si le modèle produit la valeur Blogs, Joe&Posts, Susan, alors le livre finira avec deux auteurs Blogs, Joe et Posts, Susan. Si le modèle produit la valeur Blogs, Joe;Posts, Susan, alors ce livre aura un auteur avec un nom assez étrange.

Les tableaux de connexions affectent les métadonnées écrites dans le livre quand il est sauvegardé sur le disque ou copié sur le périphérique. Les tableaux de connexions n’affecte pas les métadonnées utilisées par Enregistrer sur le disque et Envoyer au périphérique. A la place, les noms de fichiers sont construits en utilisant les modèles entrés dans la fenêtre de préférence appropriée.

Utilisation des fonctions dans les modèles - Mode de fonctionnement unique¶

Supposons que vous vouliez afficher la valeur d’un champ en casse majuscules alors que ce champ est normalement en casse titre. Vous pouvez le faire en utilisant les fonctions de modèle. Par exemple, pour afficher le titre en casse majuscules, utilisez la fonction uppercase, comme dans {title:uppercase()}. Pour l’afficher en casse titre, utilisez la fonction {title:titlecase()}.

Les fonctions sont placées dans la partie format du modèle, après le : et avant le premier | ou le } de fermeture si aucun préfixe/suffixe n’est utilisé. Si vous avez à la fois une référence de format et de fonction, la fonction vient après un deuxième :. Les fonctions renvoient la valeur de la colonne spécifiée dans le modèle, convenablement modifiée.

La syntaxe pour utiliser les fonctions est l’une des suivantes

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

Les noms de fonctions doivent toujours être suivis de parenthèses ouvrantes et fermantes. Certaines fonctions nécessitent des valeurs supplémentaires (arguments), qui sont placées à l’intérieur des parenthèses. Les arguments sont séparés par des virgules. Les virgules Littérales (les virgules en tant que texte, et non en tant que séparateurs d’arguments) doivent être précédées d’une barre oblique inversée (\) . Le dernier (ou le seul) argument ne peut pas contenir de parenthèse fermante textuelle.

Les fonctions sont évaluées avant les spécifications de format et le préfixe/suffixe. Voir plus bas pour un exemple d’utilisation à la fois d’un format et d’une fonction.

Important : Si vous avez de l’expérience en programmation, veuillez noter que la syntaxe du Mode Fonction Unique n’est pas celle à laquelle vous vous attendez. Les chaînes de caractères ne sont pas citées et les espaces sont significatifs. Tous les arguments sont considérés comme des constantes ; il n’y a pas d’expressions.

N’utilisez pas les sous-modèles (`{ … }`) comme arguments de fonction. A la place, utilisez plutôt Mode Programme Modèle et Mode Programme Général.

Notes sur l’appel de fonctions en Mode Fonction Unique :

Lorsque les fonctions sont utilisées en Mode Fonction Unique, le premier paramètre, value, est automatiquement remplacé par le contenu du champ spécifié dans le modèle. Par exemple, lorsque le modèle {title:capitalize()} est traité, le contenu du champ title est passé comme paramètre value à la fonction capitalize.
Dans la documentation des fonctions, la notation [quelque chose]* signifie que quelque chose peut être répété zéro fois ou plus. La notation [quelque chose]+ signifie que quelque chose est répété une ou plusieurs fois (doit exister au moins une fois).
Certaines fonctions utilise des expressions régulières. Dans le langage des modèles, la correspondance des expressions régulières est insensible à la casse.

Les fonctions sont documentées dans Référence des modèles de fonctions. La documentation vous indique les arguments requis par les fonctions et ce qu’elles font. Par exemple, voici la documentation de la fonction ifempty.

ifempty(value, text_if_empty) – si value n’est pas vide, elle est retournée, sinon s’est text_if_empty qui est retournée.

Vous voyez que la fonction requiert deux arguments, value et text_if_empty. Cependant, parce que nous utilisons le Mode Fonction Unique, nous omettons l’argument value, en ne passant que text_if_empty. Par exemple, ce modèle :

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

affiche les étiquettes d’un livre, s’il y en a. Si le livre n’a pas d’étiquettes, il affiche Aucune étiquette sur ce livre.

Les fonctions suivantes sont utilisable en Mode Fonction Unique car leur premier paramètre est value.

capitalize(value) – retourne value avec la première lettre en majuscule et le reste en minuscule.
ceiling(value) – retourne le plus petit entier supérieur ou égal à value.
cmp(value, y, lt, eq, gt) – compare value et y après les avoir convertis en nombres.
contains(value, pattern, text_if_match, text_if_not_match) – vérifie si la valeur correspond à l’expression régulière pattern.
date_arithmetic(value, calc_spec, fmt) – Calcule une nouvelle date à partir value``date`` en utilisant calc_spec.
floor(value) – retourne le plus grand entier inférieur ou égal à value.
format_date(value, format_string) – formater la valeur, qui doit être une chaîne de date, à l’aide de format_string, en retourant une chaîne.
format_number(value, template) – interprète value comme un nombre et formate ce nombre en utilisant un modèle de formatage Python comme {0:5.2f} ou {0:,d} ou ${0:5,.2f}.
fractional_part(value) – retourne la partie décimale de la valeur.
human_readable(value) – s’attend à ce que valeur soit un nombre et retourne une chaîne représentant ce nombre en Ko, Mo, Go, etc.
ifempty(value, text_if_empty) – si value n’est pas vide, elle est retournée, sinon s’est text_if_empty qui est retournée.
language_strings(value, localize) – retourne les noms des langue pour les codes de langue (voir ici pour les noms et les codes) passé dans value.
list_contains(value, separator, [pattern, found_val,]* not_found_val) – interprète value comme une liste d’éléments séparés par un separator, en vérifiant le pattern par rapport à chaque élément de la liste.
list_count(value, separator) – interprète la valeur comme une liste d’éléments séparés par separator et retourne le nombre d’éléments dans la liste.
list_count_matching(value, pattern, separator) – interprète value comme une liste d’éléments séparés par separator, et retourne le nombre d’éléments de la liste qui correspondent à l’expression régulière pattern.
list_item(value, index, separator) – interprète value comme une liste d’éléments séparés par un separator, en retournant l’élément a l”index.
list_sort(value, direction, separator) – retourne value triée en utilisant un tri lexical insensible à la casse.
lookup(value, [pattern, key,]* else_key) – les patterns seront comparés à value dans l’ordre.
lowercase(value) – retourne value en minuscules.
mod(value, y) – retourne floor du reste de value / y.
rating_to_stars(value, use_half_stars) – retourne value sous forme de chaîne de caractères étoilés (★).
re(value, pattern, replacement) – retourne value après application de l’expression régulière.
re_group(value, pattern [, template_for_group]*) – retourne une chaîne obtenue en appliquant l’expression régulière pattern à value et en remplaçant chaque instance correspondante
round(value) – retourne l’entier le plus proche de value.
select(value, key) – interprète value comme une liste d’éléments séparés par des virgules, chaque élément ayant la forme id:id_value (le format identifiant de Calibre).
shorten(value, left_chars, middle_text, right_chars) – retourne une version abrégée de value
str_in_list(value, separator, [string, found_val,]+ not_found_val) – interprète value comme une liste d’éléments séparés par separator puis compare string à chaque valeur de la liste.
subitems(value, start_index, end_index) – cette fonction décompose les listes d’éléments hiérarchiques de type balise, tels que les genres.
sublist(value, start_index, end_index, separator) – interprète value comme une liste d’éléments séparés par separator, retournant une nouvelle liste composée des éléments de start_index à end_index.
substr(value, start, end) – retourne le start jusqu’au end``ème caractère de ``value.
swap_around_articles(value, separator) – retourne value avec les articles déplacés à la fin.
swap_around_comma(value) – étant donné une valeur de la forme B, A, retourne A B.
switch(value, [patternN, valueN,]+ else_value) – pour chaque paire patternN, valueN, vérifie si la valeur correspond à l’expression régulière patternN
test(value, text_if_not_empty, text_if_empty) – retourne text_if_not_empty si la valeur n’est pas vide, sinon retourne text_if_empty.
titlecase(value) – retourne value en case de titre (premiére lettre de chaque mot en majuscule).
transliterate(value) – retourne une chaîne en alphabet latin formée par l’approximation du son des mots de value.
uppercase(value) – retourne value en majuscules.

Utilisation des fonctions et du formatage dans le même modèle

Supposons que vous ayez une colonne personnalisée de nombres entiers, ##myint, que vous voulez afficher avec des zéros en tête, comme dans 003. Une façon de le faire est d’utiliser le format 0>3s. Cependant, par défaut, si un nombre (entier ou flottant) est égal à zéro, la valeur est affichée sous la forme d’une chaîne vide, de sorte que les valeurs nulles produiront la chaîne vide, et non 000. Si vous voulez voir les valeurs 000, vous devez utiliser à la fois la chaîne de format et la fonction ifempty pour transformer la valeur vide en zéro. Le modèle serait

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

Notez que vous pouvez également utiliser le préfixe et le suffixe. Si vous voulez que le numéro apparaisse sous la forme [003] ou [000], utilisez alors le modèle

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

Mode Programme Général¶

Le Mode Programme Général (MPG) remplace les expressions modèles par un programme écrit dans le langage modèle. La syntaxe de ce langage est définie par la grammaire suivante

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 |
                    '(' 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 ] ] ')'
list_expr       ::= top_expression
break_expr      ::= 'break'
continue_expr   ::= 'continue'
separator_expr  ::= top_expression
start_expr      ::= top_expression
stop_expr       ::= top_expression
step_expr       ::= top_expression
limit_expr      ::= top_expression

Notes :

une top_expression a toujours une valeur. La valeur d’une expression_list est la valeur de la dernière top_expression Par exemple, la valeur de la liste d’expressions 1;2;'foobar';3 est 3.
Dans un contexte logique, toute valeur non vide est True.
Dans un contexte logique, la valeur vide est False.
Les chaînes de caractères et les nombres peuvent être utilisés indifféremment. Par exemple, 10 et '10' sont la même chose.
Les commentaires sont des lignes commençant par le caractère « # ». Les commentaires commençant plus loin dans une ligne ne sont pas pris en charge.

Préséance de l’opérateur

L’ordre de préséance de l’opérateurs (ordre d’évaluation), du plus élevé (évalué en premier) au plus bas (évalué en dernier), est le suivant :

Appels de fonctions, constantes, expressions entre parenthèses, expressions d’instructions, expressions d’affectation, références de champs.
Les opérateurs unaires plus (+) et moins (-). Ces opérateurs s’évaluent de droite à gauche.

Ces opérateurs et tous les autres opérateurs arithmétiques renvoient des entiers si l’expression donne une partie fractionnaire égale à zéro. Par exemple, si une expression renvoie 3.0, elle est transformée en 3.
Multiplier (*) et diviser (/). Ces opérateurs sont associatifs et s’évaluent de gauche à droite. Utilisez les parenthèses si vous souhaitez modifier l’ordre d’évaluation.
Additionner (+) et soustraire (-). Ces opérateurs sont associatifs et s’évaluent de gauche à droite.
Comparaisons de nombres et de chaînes de caractères. Ces opérateurs renvoient '1' si la comparaison réussit, sinon la chaîne vide (''). Les comparaisons ne sont pas associatives : a < b < c est une erreur de syntaxe.
Concaténation de chaînes de caractères (&). L’opérateur & renvoie une chaîne de caractères formée par la concaténation des expressions de gauche et de droite. Exemple : « “aaa” & “bbb”`` renvoie « “aaabbb”``. L’opérateur est associatif et s’évalue de gauche à droite.
Unaire non logique (!). Cet opérateur renvoie '1' si l’expression est fausse (évaluée à la chaîne vide), sinon ''.
L’opérateur logique et (&&). Cet opérateur renvoie “1” si les deux expressions de gauche et de droite sont vraies, ou la chaîne vide '' si l’une ou l’autre est fausse. Il est associatif, s’évalue de gauche à droite, et fait du court-circuitage.
Logique ou (||). Cet opérateur renvoie '1' si l’expression de gauche ou de droite est vraie, ou '' si les deux sont fausses. Il est associatif, s’évalue de gauche à droite, et fait du court-circuitage. C’est un or inclusif, qui renvoie « 1 » si les deux expressions de gauche et de droite sont vraies.

Références des champs

Un field_reference est évalué à la valeur du champ de métadonnées nommé par le nom de la consultation qui suit le « $ » ou le « $$ ». L’utilisation de $ équivaut à l’utilisation de la fonction :ref:`ff_field. L’utilisation de $$ équivaut à l’utilisation de la fonction raw_field. Exemples :

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

Expressions if

Les expressions If évaluent d’abord la condition. Si la condition est True (une valeur non vide), alors expression_list de la clause then est évaluée. Si elle est False, expression_list de la clause elif ou else est évaluée si elle est présente. Les parties if et else sont facultatives. Les mots if ``, ``then, elif ``, ``else et fi sont réservés ; vous ne pouvez pas les utiliser comme noms d’identifiants. Vous pouvez mettre des retours à la ligne et des espaces partout où cela a un sens. La condition est une top_expression et non une expression_list ; les points-virgules ne sont pas autorisés. Les expression_list sont des séquences de top_expressions séparées par des points-virgules. Une expression if renvoie le résultat de la dernière top_expressions de la top_expression évaluée, ou la chaîne vide si aucune liste d’expression n’a été évaluée.

Exemples:

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

Exemple de if imbriqué:

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

Comme dit plus haut, un if produit une valeur. Cela signifie que tous les cas suivants sont équivalents

* 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

Par exemple, ce programme retourne la valeur de la colonne series si le livre a une série, sinon la valeur de la colonne title :

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

Expressions for

L’expression for itère sur une liste de valeurs, en les traitant une par une. L’expression list_expression doit être évaluée soit par un nom de champ de métadonnées, par exemple tags ou #genre, soit par une liste de valeurs. Si le résultat est un lookup name valide, alors la valeur du champ est récupérée et le séparateur spécifié pour ce type de champ est utilisé. Si le résultat n’est pas un nom de référence valide, il est supposé être une liste de valeurs. La liste est supposée être séparée par des virgules, sauf si le mot-clé optionnel separator est fourni, auquel cas les valeurs de la liste doivent être séparées par le résultat de l’évaluation de l’expression separator_expr. Un séparateur ne peut pas être utilisé si la liste est générée par range. Chaque valeur de la liste est assignée à la variable spécifiée puis la expression_list est évaluée. Vous pouvez utiliser break pour sortir de la boucle, et continue pour revenir au début de la boucle pour la prochaine itération.

Exemple : Ce modèle supprime le premier nom hiérarchique pour chaque valeur dans le genre (#genre), en construisant une liste avec les nouveaux noms

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

Si le Genre original est Histoire.Militaire, Science Fiction.Histoire alternative, Lisez-moi, alors le modèle renvoie Militaire, Histoire alternative, Lisez-moi. Vous pouvez utiliser ce modèle dans le calibre Modifier les métadonnées par lot → Rechercher & remplacer avec Rechercher après défini à modèe pour supprimer le premier niveau de la hiérarchie et attribuer la valeur résultante à Genre.

Note : la dernière ligne du modèle, new_tags, n’est pas strictement nécessaire dans ce cas car for renvoie la valeur de la dernière top_expression de la liste d’expressions. La valeur d’une affectation est la valeur de son expression, donc la valeur de l’instruction for est ce qui a été affecté à new_tags.

Définition de la fonction

Si vous avez répète du code dans un modèle, vous pouvez mettre ce code dans une fonction locale. Le mot clé def commence la définition. Il est suivi par le nom de la fonction, la liste des arguments, puis le code de la fonction. La définition de la fonction se termine par le mot-clé fed.

Les arguments sont positionnels. Lorsqu’une fonction est appelée, les arguments fournis sont comparés de gauche à droite aux paramètres définis, la valeur de l’argument étant attribuée au paramètre. C’est une erreur de fournir plus d’arguments que de paramètres définis. Les paramètres peuvent avoir des valeurs par défaut, comme « a = 25 ». Si un argument n’est pas fourni pour ce paramètre, alors la valeur par défaut est utilisée, sinon le paramètre est défini par la chaîne vide.

L’instruction return peut être utilisée dans une fonction locale.

Une fonction doit être définie avant de pouvoir être utilisée.

Exemple : Ce modèle calcule une durée approximative en années, mois et jours à partir d’un nombre de jours. La fonction to_plural() met en forme les valeurs calculées. Notez que l’exemple utilise également l’opérateur &:

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

Opérateurs relationnels

Les opérateurs relationnels retourne '1' si la comparaison est vraie, sinon la chaîne vide ('').

Il existe deux formes d’opérateurs relationnels : les comparaisons de chaînes de caractères et les comparaisons numériques.

Les comparaisons de chaînes de caractères effectuent une comparaison insensible à la casse en utilisant l’ordre lexical. Les opérateurs de comparaison de chaînes pris en charge sont ==, !=, <, <=, >, =, in, inlist et inlist_field. Pour l’opérateur in, le résultat de l’expression de gauche est interprété comme un motif d’expression régulière. L’opérateur in est True si la valeur de l’expression régulière de gauche correspond à la valeur de l’expression de droite.

L’opérateur inlist est vrai si l’expression régulière de gauche correspond à l’un des éléments de la liste de droite où les éléments de la liste sont séparés par des virgules. L’opérateur inlist_field est vrai si l’expression régulière de gauche correspond à l’un des éléments du champ (colonne) nommé par l’expression de droite, en utilisant le séparateur défini pour le champ. NB : l’opérateur inlist_field requiert que l’expression de droite sui est évaluée soit un nom de champ, alors que l’opérateur inlist requiert que l’expression de droite qui est évaluée soit une chaîne de caractères contenant une liste séparée par des virgules. A cause de cette différence, inlist_field est substantiellement plus rapide que inlist car aucune conversion de chaîne ou construction de liste n’est effectuée. Les expressions régulières sont insensibles à la casse.

Les opérateurs de comparaison numérique sont ==#, !=#, <#, <=#, >#, >=#. Les expressions de gauche et de droite doivent être évaluées par des valeurs numériques, à deux exceptions près : la chaîne de caractères « None » (champ indéfini) et la chaîne de caractères vide sont évaluées par la valeur zéro.

Exemples :

program:field('series') == 'foo' retourne '1' si la série du livre est foo, sinon ''.

Program: 'f.o' in field('series') renvoie “1”` si la série du livre correspond à l’expression régulière f.o (par exemple, foo, Off Onyx, etc.), sinon ''.

program: 'science' inlist $#genre retourne '1' si l’une des valeurs du genres du livre correspond à l’expression régulière science, par exemple, Science, Histoire de la science, Science Fiction etc., sinon ''.

program: '^science$' inlist $#genre` retourne `'1' si l’un des genres du livre correspond exactement à l’expression régulière ^science$, par exemple, Science, sinon ''. Les genres Histoire des sciences et Science Fiction ne correspondent pas.

program: 'asimov' inlist $authors retourne '1' si un auteur correspond à l’expression régulière asimov, ex., Asimov, Isaac ou Isaac Asimov, sinon ''.

program: 'asimov' inlist_field 'authors' retourne '1' si un auteur correspond à l’expression régulière asimov, ex., Asimov, Isaac ou Isaac Asimov, sinon ''.

program: 'asimov$' inlist_field 'authors' retourne '1' si un auteur correspond à l’expression régulière asimov$, ex., Isaac Asimov, sinon ''. Il ne correspond pas a Asimov, Isaac a cause de l’ancre $ dans l’expression régulière.

program: if field('series') != 'foo' then 'bar' else 'mumble' fi retourne 'bar' si la série du livre n’est pas foo. Sinon, retourne 'mumble'.

program: if field('series') == 'foo' || field('series') == '1632' then 'yes' else 'no' fi retourne 'yes' si séries existe soit foo soit 1632, sinon 'no'.

program: if '^(foo|1632)$' in field('series') then 'yes' else 'no' fi retourne 'yes' si la série existe soit foo ou 1632, sinon 'no'.

program: if '11' > '2' then 'yes' else 'no' fi renvoie `”no”`` parce que l’opérateur > fait une comparaison lexicale.

Program: if 11 ># 2 then 'yes' else 'no' fi renvoie 'yes' parce que l’opérateur ># effectue une comparaison numérique.

Fonction en Mode Programme Général

Voir Référence des modèles de fonctions pour la liste des fonctions intégrées au langage des modèles.

Notes :

Contrairement à Single Function Mode, en Mode Programme Général, vous devez spécifier le premier paramètre value.
Tous les paramètres sont des listes d’expressions (voir la grammaire ci-dessus).

Programmes plus complexes dans les expressions modèles - Mode Programme de Modèles¶

Le Mode Programme de Modèle (MPM) est un mélange du Mode de Programme Général et du Mode Fonction Unique. Le MPM diffère du Mode Fonction Unique en ce qu’il permet d’écrire des expressions de modèle qui font référence à d’autres champs de métadonnées, utilisent des fonctions imbriquées, modifient des variables et font de l’arithmétique. Il diffère du Mode Programme Général en ce que le modèle est contenu entre les caractères {` et } et ne commence pas par le mot program:. La partie programme du modèle est une liste d’expressions du Mode Programme Général.

Exemple : supposons que vous vouliez qu’un modèle affiche la série d’un livre s’il en a une, sinon la valeur d’un champ personnalisé #genre. Vous ne pouvez pas faire cela dans le mode Mode Fonction Unique car vous ne pouvez pas faire référence à un autre champ de métadonnées dans une expression de modèle. En MPM, vous le pouvez, comme le montre l’expression suivante

{series_index:0>7.1f:'ifempty($, -5)'}

L’exemple montre plusieurs choses :

MPP est utilisé si l’expression commence par :' et se termine par '}. Tout le reste est supposé être en Mode Fonction Unique.

Si le modèle contient un préfixe et un suffixe, l’expression se termine par '| où le | est le délimiteur du préfixe. Exemple :
```
{series_index:0>7.1f:'ifempty($, -5)'|prefix | suffix}
```
Les fonctions doivent être données avec tous leurs arguments. Par exemple, les fonctions intégrées standard doivent recevoir le paramètre initial value.
La variable $ est utilisable comme argument value et représente la valeur du champ nommé dans le modèle, series_index dans ce cas.
les espaces sont ignorés et peuvent être utlisés n’importe où dans l’expression.
les chaînes constantes sont entre guillemets, soit ' ou ".

En MPM, l’utilisation des caractères {` et } dans les chaînes de caractères peut conduire à des erreurs ou des résultats inattendus parce qu’ils confondent le processeur de modèle. Il essaie de les traiter comme des limites d’expression de modèle et non comme des caractères. Dans certains cas, mais pas dans tous, vous pouvez remplacer un { par [[ et un } par ]]. En général, si votre programme contient des caractères { et }, vous devriez utiliser le Mode Programme Général.

Mode Programmation Python¶

Mode Programmation Python (MPP) vous permet d’écrire des modèles en utilisant le langage Python natif et l’API de calibre. L’API de la base de données sera la plus utile ; une discussion plus approfondie dépasse le cadre de ce manuel. Les modèles MPP sont plus rapides et peuvent faire des opérations plus compliquées, mais vous devez savoir comment écrire du code en Python en utilisant l’API calibre.

Un modèle de MPP commence par :

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'

Vous pouvez ajouter le texte ci-dessus à votre modèle en utilisant le menu contextuel, généralement accessible par un clic droit. Les commentaires ne sont pas significatifs et peuvent être supprimés. Vous devez utiliser l’indentation python.

L’objet context prend en charge str(context) qui retourne une chaîne de caractères du contenu du contexte, et context.attributes qui retourne une liste des noms d’attributs dans le contexte.

L’attribut context.funcs permet d’appeler les fonctions modèles intégrés et utilisateurs, ainsi que les modèles stockés MPG/Python, afin que vous puissiez les exécuter directement dans votre code. Les fonctions sont récupérées à l’aide de leur nom. Si le nom entre en conflit avec un mot clé Python, ajoutez un trait de underscore à la fin du nom. Exemples :

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

Voici un exemple de modèle MPP qui produit une liste de tous les auteurs d’une série. La liste est stockée dans une Colonne construite à partir d’autres colonnes, se comporte comme des étiquettes. Elle est affichée dans Détails du livre et l’option sur des lignes séparées est cochée (dans Préférences → Apparence et présentation → Détails du livre). Cette option exige que la liste soit séparée par des virgules. Pour satisfaire à cette exigence, le modèle convertit les virgules dans les noms d’auteurs en points-virgules puis construit une liste d’auteurs séparés par des virgules. Les auteurs sont ensuite triés, c’est pourquoi le modèle utilise 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))

La sortie dans Détails du livre ressemble à ceci :

Dialogue de conversion des livres numériques

Modèles stockés¶

Les modes Mode Général de Programmation et Mode Programmation Python permettent d’enregistrer des modèles et d’appeler ces modèles à partir d’un autre modèle, de la même manière que l’on appelle des fonctions stockées. Vous enregistrez les modèles en utilisant Préférences → Avancées → Modèles de fonctions. Plus d’informations sont fournies dans cette boîte de dialogue. Vous appelez un modèle de la même manière que vous appelez une fonction, en passant des arguments positionnels si vous le souhaitez. Un argument peut être n’importe quelle expression. Exemples d’appel d’un modèle, en supposant que le modèle stocké est nommé foo

foo() – appelle le modèle en ne passant aucun argument.
foo(a, b) appelle le modèle en passant les valeurs des deux variables a et b.
foo(if field('series') then field('series_index') else 0 fi) – si le livre a series alors passez le series_index, sinon passez la valeur 0.

En MGP, vous récupérez les arguments passés dans l’appel au modèle stocké en utilisant la fonction arguments. Cette fonction déclare et initialise des variables locales, en fait des paramètres. Les variables sont positionnelles ; elles obtiennent la valeur du paramètre donné dans l’appel à la même position. Si le paramètre correspondant n’est pas fourni dans l’appel, alors arguments attribue à cette variable la valeur par défaut fournie. S’il n’y a pas de valeur par défaut, la variable prend la valeur de la chaîne vide. Par exemple, la fonction arguments suivante déclare 2 variables, key, alternate :

arguments(key, alternate='series')

Par exemple, en supposant encore une fois que le modèle stocké est nommé foo :

foo('#myseries') – l’argument key se voit attribuer la valeur myseries' et l’argument alternate se voit attribuer la valeur par défaut 'series'.
foo('series', '#genre') la variable key prend la valeur 'series' et la variable alternate prend la valeur '#genre'.
foo() – la variable key se voit attribuer la chaîne vide et la variable alternate se voit attribuer la valeur 'series'.

En MPP, les arguments sont passés dans le paramètre arguments, qui est une liste de chaînes de caractères. Il n’y a aucun moyen de spécifier des valeurs par défaut. Vous devez vérifier la longueur de la liste arguments pour être sûr que le nombre d’arguments est celui que vous attendez.

Une façon simple de tester les modèles stockés est d’utiliser le dialogue « Testeur de modèle ». Pour faciliter l’accès, donnez-lui un raccourci clavier dans Préférences → Avancé → Raccourcis clavier → Tester le modèle`. Donner un raccourci au dialogue Modèles stockés aidera à passer plus rapidement du testeur à l’édition du code source du modèle stocké.

Fournir des informations supplémentaires aux modèles¶

Un développeur peut choisir de transmettre des informations supplémentaires au processeur du modèle, telles que des métadonnées de livre spécifiques à l’application ou des informations sur ce qui est demandé au processeur. Un modèle peut accéder à ces informations et les utiliser pendant l’évaluation.

Développeur : comment transmettre des informations supplémentaires

L’information supplémentaire est un dictionnaire Python contenant des paires nom_variable : valeur_variable où les valeurs doivent être des chaînes. Le modèle peut accéder au dictionnaire, en créant des variables locales nommées nom_de_variable contenant la valeur variable_valeur. L’utilisateur ne peut pas changer le nom, il est donc préférable d’utiliser des noms qui n’entreront pas en collision avec d’autres variables locales du modèle, par exemple en préfixant le nom par un trait de soulignement.

Ce dictionnaire est passé au processeur de modèle (le formatter) en utilisant le paramètre nommé global_vars=votre_dict. La signature complète de la méthode est :

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

Rédacteur de modèles : comment accéder aux informations complémentaires

Vous accédez aux informations supplémentaires (le dictionnaire globals) dans un modèle en utilisant la fonction de modèle :

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

où id est un nom de variable légale quelconque. Cette fonction vérifie si les informations supplémentaires fournies par le développeur contiennent le nom. Si c’est le cas, la fonction attribue la valeur fournie à une variable locale modèle avec ce nom. Si le nom ne figure pas dans les informations supplémentaires et si une « expression » est fournie, cette « expression » est évaluée et le résultat est attribué à la variable locale. Si ni une valeur ni une expression n’est fournie, la fonction attribue la chaîne vide ('') à la variable locale.

Un modèle peut définir une valeur dans le dictionnaire globals en utilisant la fonction de modèle:

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

Cette fonction définit la paire clé:valeur du dictionnaire globals id:value où value est la valeur de la variable locale du modèle id. Si cette variable locale n’existe pas, alors valeur est fixée au résultat de l’évaluation de expression.

Notes sur la différence entre les modes¶

Les trois modes de programmation, Mode Fonction Simple (MFS), Mode Modèle de Programmation (MMP), et Mode Général de Programmation (MGP), fonctionnent différemment. Le MFS est destiné à être “simple” et cache donc beaucoup de bits de langage de programmation.

Différences :

Dans MFS, la valeur de la colonne est toujours passée comme premier argument “invisible” à une fonction incluse dans le modèle.
Le MFS ne supporte pas la différence entre les variables et les chaînes de caractères ; toutes les valeurs sont des chaînes de caractères.
Le modèle SFM suivant renvoie soit le nom de la série, soit la chaîne « pas de série »
```
{series:ifempty(no series)}
```
Le modèle équivalent dans MPM est
```
{series:'ifempty($, 'no series')'}
```
Le modèle équivalent dans MGP est
```
program: ifempty(field('series'), 'no series')
```
Le premier argument de ifempty est la valeur du champ série. Le second argument est la chaîne no series. Dans SFM, le premier argument, la valeur du champ, est automatiquement passé (l’argument invisible).
Plusieurs fonctions du modèle, par exemple booksize() et current_library_name(), ne prennent aucun argument. En raison de l“« argument invisible », vous ne pouvez pas utiliser ces fonctions dans SFM.
Les fonctions imbriquées, où une fonction appelle une autre fonction pour calculer un argument, ne peuvent pas être utilisées dans SFM. Par exemple, ce modèle, destiné à renvoyer les 5 premiers caractères de la valeur de la série en majuscules, ne fonctionnera pas dans SFM
```
{series:uppercase(substr(0,5))}
```
MPM et MPG soutiennent des fonctions imbriquées. Le modèle ci-dessus dans MPM serait
```
{series:'uppercase(substr($, 0,5))'}
```
Dans MPG, ce serait
```
program: uppercase(substr(field('series'), 0,5))
```
Comme indiqué dans la section Mode de Programmation des Modèles ci-dessus, l’utilisation des caractères { et } dans les chaînes de caractères MPM peut conduire à des erreurs ou à des résultats inattendus car ils perturbent le processeur de modèles. Il essaie de les traiter comme des limites de modèles et non comme des caractères. Dans certains cas, mais pas dans tous, vous pouvez remplacer un { par [[ et un } par ]]`. En général, si votre programme contient des caractères ``{ et }, vous devriez utiliser le Mode Général de Programmation.

Fonctions des modèles Python définis par l’utilisateur¶

Vous pouvez ajouter vos propres fonctions Python au processeur de modèles. Ces fonctions peuvent être utilisées dans l’un des trois modes de programmation du modèle. Les fonctions sont ajoutées en allant dans Préférences → Avancé → Fonctions de modèle. Les instructions sont affichées dans cette boite de dialogue. Notez que vous pouvez utiliser les Modèles Python dans un but similaire. Comme l’appel à des fonctions définies par l’utilisateur est plus rapide que l’appel à un modèle Python, les fonctions définies par l’utilisateur peuvent être plus efficaces en fonction de la complexité de ce que fait la fonction ou le modèle.

Notes spéciales pour la sauvergarde/l’envoi des modèles¶

Un traitement spécial est appliqué quand un modèle est utilisé dans un modèle Enregistrer sur le disque ou Envoyer au périphérique. Les valeurs des champs sont nettoyées, les caractères qui sont propres aux systèmes de fichiers sont remplacées par des traits de soulignement, y compris les barres obliques. Cela signifie que le texte d’un champ ne peut pas être utilisé pour créer des dossiers. Toutefois, les barres obliques ne sont pas modifiés dans des chaînes préfixe ou suffixe. Vous pouvez donc insérer des barres obliques qui et provoquer ainsi la création de dossiers. Ainsi, vous pouvez créer une structure de dossier avec des profondeurs variables.

Par exemple, supposons que nous voulons que la structure des dossiers soit series/series_index - titre, en prévoyant que si la série n’existe pas, alors le titre devrait être dans le dossier racine (le premier dossier, pas le sous-dossier). Le modèle pour faire cela est :

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

La barre oblique et le trait d’union apparaissent uniquement si la série n’est pas vide.

La fonction de recherche nous permet de faire le traitement encore plus poussé. Par exemple, supposons que si un livre est dans une série, alors nous voulons que la structure soit la suivante : series/series index - title.fmt.. Si le livre n’est pas dans une série, alors nous voulons que la structure des dossiers soit genre/author_sort/title.fmt. Si le livre n’a pas de genre, alors nous voulons utiliser “Inconnu”. Nous voulons deux chemins de répertoire totalement différents en fonction de la valeur de la série.

Pour accomplir cela, nous :

Créer un champ composite (donner-lui le nom de recherche #aa) contenant {series}/{series_index} - {titre}. Si la série n’est pas vide, alors ce modèle produira series/series_index - titre.
Créons une champ composite (appelons-le #bb) contenant {#genre:ifempty(Unknown)}/{author_sort}/{title}. Ce modèle produit genre/author_sort/title, où un genre vide est remplacé par Inconnu.
Paramétrez le modèle de sauvegarde à {series:lookup(.,#aa,#bb)}. Ce modèle choisit le champ composite #aa si série n’est pas vide, et le champ composite #bb si série est vide. Nous avons dès lors deux chemins de sauvegarde complètement différents, dépendant du fait que series soit vide ou pas.

Astuces¶

Utilisez le Testeur de Modèles pour tester les modèles. Ajoutez le testeur au menu contextuel des livres de la bibliothèque et/ou donnez-lui un raccourci clavier.
Les modèles peuvent utiliser d’autres modèles en faisant référence à des colonnes composites construites avec le modèle souhaité. Vous pouvez également utiliser des Modèles Stockés comme alternative.
Dans un tableau de connexions, vous pouvez paramétrer un champ à vide (ou quelque soit sont équivalent à vide) en utilisant le modèle spécial {}. Ce modèle sera toujours évalué à une chaîne vide.
La technique indiquée ci-dessus pour montrer les nombre même s’ils ont une valeur zéro fonctionne avec le champ standard series_index.

Référence des modèles de fonctions¶

Reference for all built-in template language functions