Die Calibre-Vorlagensprache

Die Calibre-Vorlagensprache wird an verschiedenen Stellen verwendet. Sie dient zur Verwaltung von Ordnerstrukturen und Dateinamen beim Speichern von Dateien aus der Calibre-Bibliothek auf eine Festplatte oder eBook-Reader. Sie wird unter anderem auch verwendet um „virtuelle“ Spalten zu definieren, die Daten von anderen Spalten enthalten.

Die grundlegende Vorlagensprache ist sehr einfach, besitzt aber sehr vielseitige Funktionen. Die grundlegende Idee dahinter ist, dass eine Vorlage aus Text und Namen in geschweiften Klammern besteht, die beim Verarbeiten durch die entsprechenden Metadaten aus dem Buch ersetzt werden. So ist beispielsweise die in Calibre verwendete Standardvorlage zur Speicherung von Büchern auf Geräten:

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

Für das Buch „The Foundation“ von „Isaac Asimov“ wird das zu:

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

Die Querstriche sind Text, die in die Vorlage eingefügt ist, wo dieser auftauchen soll. Ein Beispiel, wenn Ihre Vorlage so aussieht:

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

Für das Buch „The Foundation“ von „Isaac Asimov“ wird das zu:

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

Sie können alle in Calibre zur Verfügung stehende Metadatenfelder in einer Vorlage verwenden. Dazu gehören ebenso selbst erstellte benutzerdefinierte Spalten. Um den Vorlagennamen für eine Spalte herauszufinden, bewegt man einfach den Mauszeiger über den Kopf der Spalte. Namen von benutzerdefinierten Feldern (selbst angelegte Spalten) erkennt man an dem vorangestellten # als erstes Zeichen. Für benutzerdefinierte Felder vom Typ Serie gibt es immer ein zusätzliches Feld, dass #seriesname_index heißt und den Serienindex der Serie darstellt. Wenn Sie beispielsweise ein benutzerdefiniertes Serienfeld mit dem Namen #myseries haben, gibt es auch das Feld #myseries_index.

Zusätzlich zu den Feldern, die auf Spalten basieren können Sie auch Folgendes verwenden:

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

Wenn ein bestimmtes Buch eine bestimmte Art von Metadaten nicht besitzt, wird die entsprechende Vorlage automatisch aus dem Buch entfernt. Hier ein Beispiel:

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

Wenn das Buch eine Serie hat, ergibt die Vorlage:

Asimov, Isaac/Foundation/Second Foundation 3

und wenn das Buch keine Serie hat:

Asimov, Isaac/Second Foundation

(Calibre entfernt mehrere Querstriche sowie Leerzeichen vor oder nach einem Wort automatisch).

Erweiterte Formatierung

Mit den Vorlagen können Sie mehr machen als nur etwas zu ersetzen. Sie können auch Text unter bestimmten Bedingungen hinzufügen und festlegen, wie die eingefügten Daten formatiert werden.

First, conditionally including text. There are cases where you might want to have text appear in the output only if a field is not empty. A common case is series and series_index, where you want either nothing or the two values with a hyphen between them. calibre handles this case using a special field syntax.

Nehmen wir beispielsweise an, Sie wollen dieses Template verwenden:

{series} - {series_index} - {title}

Falls das Buch keiner Serie angehört, wird die Antwort - - Titel sein. Viele Benutzer würden als Ergebnis einfach Titel bevorzugen, also ohne Bindestriche. Benutzen Sie hierfür die erweiterte Syntax {field:|prefix_text|suffix_text}. Bei Verwendung dieser Syntax ist das Ergebnis prefix_textSERIESsuffix_text, falls das Feld den Wert SERIES besitzt. Wenn das Feld keinen Wert beinhaltet, wird das Ergebnis die leere Zeichenkette sein (nichts); Präfix und Suffix werden ignoriert. Präfix und Suffix können Leerzeichen enthalten. Verwenden Sie keine Untervorlagen (`{ … }`) oder Funktionen (siehe unten) als Präfix oder Suffix.

Durch diese Syntax können wir das oben genannte Problem mit der Serie umgehen. Dafür verwenden wir dieses Template:

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

Die Bindestriche werden nur dann enthalten sein, wenn das Buch einen Serienindex hat. Diesen hat es nur dann, wenn es eine Serie hat.

Hinweis: Sie müssen das Zeichen : einfügen, wenn Sie ein Präfix oder Suffix verwenden wollen. Außerdem müssen Sie entweder keines der Zeichen | verwenden oder beide; Wenn Sie nur eines verwenden, wie in {field:| - }, ist das unzulässig. Es ist möglich für eine der beiden Seiten keinen Text anzugeben, wie in {series:|| - }. Wenn Sie {title:||} verwenden, ist das als ob Sie {title} verwenden würden.

Formatierung: Angenommen Sie wollen sicherstellen, dass series_index immer als drei Ziffern formatiert wird, die mit Nullen beginnen. Dafür verwenden Sie:

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

Falls Sie anstatt führender Nullen führende Leerzeichen wollen, verwenden Sie:

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

Für anhängende Nullen verwenden Sie:

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

Wenn Sie mit einem Serienindex arbeiten, der Unterteilungen enthält (z.B. 1.1) werden Sie wahrscheinlich sicherstellen wollen, dass die Dezimaltrennzeichen auf einer Linie sind. Also soll zum Beispiel 1 und 2.5 als 01.00 und 02.50 angezeigt werden, damit sie richtig sortiert sind. Dafür verwenden Sie:

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

Wenn Sie nur die ersten beiden Buchstaben der Daten haben wollen, verwenden Sie:

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

The calibre template language comes from Python and for more details on the syntax of these advanced formatting operations, look at the Python documentation.

Erweiterte Funktionen

Vorlagen in benutzerdefinierten Spalten verwenden

There are sometimes cases where you want to display metadata that calibre does not normally display, or to display data in a way different from how calibre normally does. For example, you might want to display the ISBN, a field that calibre does not display. You can use custom columns for this by creating a column with the type ‚column built from other columns‘ (hereafter called composite columns), and entering a template. Result: calibre will display a column showing the result of evaluating that template. To display the ISBN, create the column and enter {identifiers:select(isbn)} into the template box. To display a column containing the values of two series custom columns separated by a comma, use {#series1:||,}{#series2}.

Composite columns can use any template option, including formatting.

You cannot change the data contained in a composite column. If you edit a composite column by double-clicking on any item, you will open the template for editing, not the underlying data. Editing the template on the GUI is a quick way of testing and changing composite columns.

Verwenden von Funktionen in Vorlagen - Einzelfunktionsmodus

Suppose you want to display the value of a field in upper case, when that field is normally in title case. You can do this (and many more things) using the functions available for templates. For example, to display the title in upper case, use {title:uppercase()}. To display it in title case, use {title:titlecase()}.

Function references appear in the format part, going after the : and before the first | or the closing }. If you have both a format and a function reference, the function comes after another :. Functions must always end with (). Some functions take extra values (arguments), and these go inside the ().

Functions are always applied before format specifications. See further down for an example of using both a format and a function, where this order is demonstrated.

The syntax for using functions is {field:function(arguments)}, or {field:function(arguments)|prefix|suffix}. Arguments are separated by commas. Commas inside arguments must be preceded by a backslash ( \ ). The last (or only) argument cannot contain a closing parenthesis ( ) ). Functions return the value of the field used in the template, suitably modified.

Important: If you have programming experience, please note that the syntax in this mode (single function) is not what you might expect. Strings are not quoted. Spaces are significant. All arguments must be constants; there is no sub-evaluation. Do not use subtemplates (`{ … }`) as function arguments. Instead, use template program mode and general program mode.

Many functions use regular expressions. In all cases, regular expression matching is case-insensitive.

The functions available are listed below. Note that the definitive documentation for functions is available in the section Function classification:

  • lowercase() – gibt den Wert des Feldes in Kleinbuchstaben zurück.

  • uppercase() – gibt den Wert des Feldes in Großbuchstaben zurück.

  • titlecase() – gibt den Wert des Feldes in Überschriftenschreibweise zurück.

  • capitalize() – gibt den Wert mit einem großen Anfangsbuchstaben und den Rest in Kleinbuchstaben zurück.

  • contains(Muster, Text_bei_Übereinstimmung, Text_bei_keiner_Übereinstimmung) – überprüft, ob das Feld Übereinstimmungen mit dem regulären Ausdruck Muster enthält. Gibt Text_bei_Übereinstimmung zurück, falls Übereinstimmungen gefunden wurden, andernfalls wird Text_bei_keiner_Übereinstimmung zurückgegeben.

  • count(Trennzeichen) – interpretiert den Wert als eine durch Trennzeichen voneinander getrennte Liste von Elementen und gibt die Anzahl der Elemente in der Liste zurück. Die meisten Listen verwenden ein Komma als Trennzeichen, aber „Autoren“ verwendet ein Et-Zeichen („&“). Beispiele: {tags:count(,)}, {authors:count(&)}

  • format_number(template) – interprets the field as a number and format that number using a Python formatting template such as „{0:5.2f}“ or „{0:,d}“ or „${0:5,.2f}“. The field_name part of the template must be a 0 (zero) (the „{0:“ in the above examples). You can leave off the leading „{0:“ and trailing „}“ if the template contains only a format. See the template language and Python documentation for more examples. Returns the empty string if formatting fails.

  • human_readable() – erwartet als Wert eine Zahl und gibt eine Zeichenkette zurück, die diese Zahl in KB, MB, GB etc. darstellt.

  • ifempty(Text) – falls das Feld nicht leer ist, wird der Wert des Feldes zurückgegeben, andernfalls Text.

  • in_list(separator, pattern, found_val, ..., not_found_val) – interpret the field as a list of items separated by separator, evaluating the pattern against each value in the list. If the pattern matches a value, return found_val, otherwise return not_found_val. The pattern and found_value can be repeated as many times as desired, permitting returning different values depending on the search. The patterns are checked in order. The first match is returned.

  • language_codes(Sprachzeichenketten) – gibt die Sprachcodes für die in Sprachzeichenketten übergebenen Zeichenketten zurück. Die Zeichenketten müssen der Sprache des aktuellen Gebietsschemas entsprechen. Sprachzeichenketten ist eine kommagetrennte Liste.

  • language_strings(Sprachcodes, lokalisieren) – gibt die Zeichenketten für die in Sprachcodes übergebenen Sprachcodes zurück. Falls lokalisieren gleich null ist, werden die Zeichenketten in Englisch zurückgegeben. Falls lokalisieren ungleich null ist, werden die Zeichenketten in der Sprache das aktuellen Gebietsschemas zurückgegeben. Sprachcodes ist eine kommagetrennte Liste.

  • list_item(Index, Trennzeichen) – interpretiert das Feld als eine durch Trennzeichen voneinander getrennte Liste von Elementen und gibt das index-te Element zurück. Das erste Element besitzt die Indexnummer null. Das letzte Element kann durch „list_item(-1,`Trennzeichen`)“ zurückgegeben werden. Falls sich das Element nicht in der Liste befindet, wird ein leerer Wert zurückgegeben. Das Trennzeichen hat die gleiche Bedeutung wie in der Funktion „count“.

  • lookup(Muster, Feld, Muster, Feld, …, sonst_Feld) – wie die Funktion „switch“, außer, dass die Argumente Feldnamen (Metadaten) sind, und kein Text. Der Wert des entsprechenden Feldes wird abgerufen und verwendet. Beachten Sie, dass - da zusammengesetzte Spalten Felder sind - Sie diese Funktion in einem zusammengesetzten Feld verwenden können, um den Wert eines anderen zusammengesetzen Feldes zu verwenden. Dies ist äußerst hilfreich bei der Konstruktion von variablen Speicherpfaden (später mehr).

  • re(pattern, replacement) – return the field after applying the regular expression. All instances of pattern are replaced with replacement. As in all of calibre, these are Python-compatible regular expressions.

  • select(Schlüssel) – interpretiert das Feld als eine kommagetrennte Liste von Elementen, wobei die Elemente die Form „ID:Wert“ besitzen. Findet das Paar, bei dem die ID gleich dem Schlüssel ist, und gibt den entsprechenden Wert zurück. Diese Funktion ist besonders hilfreich zum Extrahieren eines Wertes, wie z. B. eine ISBN-Nummer von der Reihe der Kennungen für ein Buch.

  • shorten(Zeichen_links, Text_Mitte, Zeichen_rechts) – gibt eine gekürzte Version des Feldes zurück, bestehend aus einer Anzahl von Zeichen_links Zeichen vom Beginn des Feldes, gefolgt von Text_Mitte, gefolgt von einer Anzahl von Zeichen_rechts Zeichen vom Ende der Zeichenkette. Zeichen_links und Zeichen_rechts müssen ganze Zahlen sein. Nehmen wir beispielsweise an, der Titel des Buches lautet „Ancient English Laws in the Times of Ivanhoe“ und Sie möchten, dass er in eine Zeichenkette von maximal 15 Zeichen passt. Falls Sie {title:shorten(9,-,5)} verwenden, wird das Ergebnis „Ancient E-nhoe“ sein. Falls die Feldlänge weniger als Zeichen_links + Zeichen_rechts + Länge von Text_Mitte ist, wird das Feld unverändert verwendet. Beispielsweise würde der Titel „The Dome“ nicht verändert.

  • str_in_list(separator, string, found_val, ..., not_found_val) – interpret the field as a list of items separated by separator, comparing the string against each value in the list. If the string matches a value (ignoring case), return found_val, otherwise return not_found_val. If the string contains separators, then it is also treated as a list and each value is checked. The string and found_value can be repeated as many times as desired, permitting returning different values depending on the search. The strings are checked in order. The first match is returned.

  • subitems(start_index, end_index) – This function is used to break apart lists of tag-like hierarchical items such as genres. It interprets the field as a comma-separated list of tag-like items, where each item is a period-separated list. Returns a new list made by first finding all the period-separated tag-like items, then for each such item extracting the components from start_index to end_index, then combining the results back together. The first component in a period-separated list has an index of zero. If an index is negative, then it counts from the end of the list. As a special case, an end_index of zero is assumed to be the length of the list. Examples:

    Assuming a #genre column containing "A.B.C":
        {#genre:subitems(0,1)} returns "A"
        {#genre:subitems(0,2)} returns "A.B"
        {#genre:subitems(1,0)} returns "B.C"
    Assuming a #genre column containing "A.B.C, D.E":
        {#genre:subitems(0,1)} returns "A, D"
        {#genre:subitems(0,2)} returns "A.B, D.E"
    
  • sublist(start_index, end_index, separator) – interpret the field as a list of items separated by separator, returning a new list made from the items from start_index to end_index. The first item is number zero. If an index is negative, then it counts from the end of the list. As a special case, an end_index of zero is assumed to be the length of the list. Examples assuming that the tags column (which is comma-separated) contains „A, B ,C“:

    {tags:sublist(0,1,\,)} returns "A"
    {tags:sublist(-1,0,\,)} returns "C"
    {tags:sublist(0,-1,\,)} returns "A, B"
    
  • swap_around_comma() – given a field with a value of the form B, A, return A B. This is most useful for converting names in LN, FN format to FN LN. If there is no comma, the function returns val unchanged.

  • switch(Muster, Wert, Muster, Wert, …, sonst_Wert) – für jedes Muster, Wert-Paar wird überprüft, ob das Feld dem regulären Ausdruck Muster entspricht, und falls ja, wird der entsprechende Wert zurückgegeben. Falls kein Muster übereinstimmt, wird sonst_Wert zurückgegeben. Sie können so viele Muster, Wert-Paare angeben, wie Sie möchten.

  • test(Text_falls_nicht_leer, Text_falls_leer) – gibt Text_falls_nicht_leer zurück, falls das Feld nicht leer ist, andernfalls Text_falls_leer.

  • transliterate() – gibt eine Zeichenkette in einem lateinischen Alphabet zurück, gebildet durch Annähern des Klangs der Wörter im Quellfeld. Falls beispielsweise das Quellfeld Фёдор Миха́йлович Достоевский enthält, gibt die Funktion Fiodor Mikhailovich Dostoievskii zurück.

Now, what about using functions and formatting in the same field. Suppose you have an integer custom column called #myint that you want to see with leading zeros, as in 003. To do this, you would use a format of 0>3s. However, by default, if a number (integer or float) equals zero then the field produces the empty value, so zero values will produce nothing, not 000. If you really want to see 000 values, then you use both the format string and the ifempty function to change the empty value back to a zero. The field reference would be:

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

Note that you can use the prefix and suffix as well. If you want the number to appear as [003] or [000], then use the field:

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

Verwenden von Funktionen in Vorlagen - Vorlageprogrammmodus

Der Programmmodus der Vorlagensprache unterscheidet sich vom Einzelfunktionsmodus dadurch, dass er Ihnen das Schreiben von Vorlageausdrücken erlaubt, die sich auf andere Metadatenfelder beziehen, Werte verändern und Rechenoperationen durchführen. Er ist eine ziemlich vollständige Programmiersprache.

Sie können die die oben im Vorlageprogrammmodus dokumentierten Funktionen verwenden. Siehe unten für Details.

Um mit einem Beispiel zu beginnen, nehmen wir an, dass Sie Ihre Vorlage die Serie für ein Buch – falls es eine hat – anzeigen lassen wollen, andernfalls soll der Wert eines benutzerdefinierten Felds #Genre angezeigt werden. Sie können dies in der einfachen Sprache nicht tun, da Sie innerhalb eines Vorlageausdrucks kein anderes Metadatenfeld referenzieren können. Im Programmmodus können Sie dies tun. Der folgende Ausdruck funktioniert:

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

Das Beispiel zeigt mehrere Dinge:

  • Der Programmmodus wird verwendet, falls der Ausdruck mit :' beginnt und mit ' endet. Andernfalls wird von einer Einzelfunktion ausgegangen.
  • Die Variable $ steht für das Feld, auf das der Ausdruck angewendet wird, in diesem Fall #series.
  • Funktionen müssen sämtliche ihrer Variablen übergeben werden. Es existiert kein Standardwert. Beispielsweise muss den standardmäßig integrierten Funktionen ein zusätzlicher, das Quellfeld bezeichnender Ausgangsparameter übergeben werden, der einen wesentlichen Unterschied zum Einzelfunktionsmodus darstellt.
  • Leerzeichen werden ignoriert und können überall innerhalb des Ausdrucks verwendet werden.
  • Zeichenkettenkonstanten werden in sich entsprechenden Anführungszeichen eingeschlossen, entweder ' oder ".

Die Sprache ähnelt funktionalen Sprachen in der Form, dass sie nahezu vollständig aus Funktionen aufgebaut ist. Eine Anweisung ist eine Funktion. Ein Ausdruck ist eine Funktion. Konstanten und Bezeichner können als Funktionen gesehen werden, die den Wert zurückgeben, der durch die Konstante bezeichnet oder im Bezeichner gespeichert ist.

Der Syntax der Sprache wird durch die folgende Grammatik gezeigt:

constant   ::= " string " | ' string ' | number
identifier ::= sequence of letters or ``_`` characters
function   ::= identifier ( statement [ , statement ]* )
expression ::= identifier | constant | function | assignment
assignment ::= identifier '=' expression
statement  ::= expression [ ; expression ]*
program    ::= statement

Kommentare sind Zeilen mit einem ‚#‘-Zeichen am Zeilenanfang.

An expression always has a value, either the value of the constant, the value contained in the identifier, or the value returned by a function. The value of a statement is the value of the last expression in the sequence of statements. As such, the value of the program (statement):

1; 2; 'foobar'; 3

ist 3.

Another example of a complex but rather silly program might help make things clearer:

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

Dieses Programm macht Folgendes:

  • specify that the field being looked at is series_index. This sets the value of the variable $.
  • calls the substr function, which takes 3 parameters (str, start, end). It returns a string formed by extracting the start through end characters from string, zero-based (the first character is character zero). In this case the string will be computed by the strcat function, the start is 0, and the end is 6. In this case it will return the first 6 characters of the string returned by strcat, which must be evaluated before substr can return.
  • calls the strcat (string concatenation) function. Strcat accepts 1 or more arguments, and returns a string formed by concatenating all the values. In this case there are three arguments. The first parameter is the value in $, which here is the value of series_index. The second paremeter is the constant string '->'. The third parameter is the value returned by the cmp function, which must be fully evaluated before strcat can return.
  • The cmp function takes 5 arguments (x, y, lt, eq, gt). It compares x and y and returns the third argument lt if x < y, the fourth argument eq if x == y, and the fifth argument gt if x > y. As with all functions, all of the parameters can be statements. In this case the first parameter (the value for x) is the result of dividing the series_index by 2. The second parameter y is the constant 1. The third parameter lt is a statement (more later). The fourth parameter eq is the constant string 'eq'. The fifth parameter is the constant string 'gt'.
  • The third parameter (the one for lt) is a statement, or a sequence of expressions. Remember that a statement (a sequence of semicolon-separated expressions) is also an expression, returning the value of the last expression in the list. In this case, the program first assigns the value 1 to a local variable c, then returns a substring made by extracting the c’th character to the end. Since c always contains the constant 1, the substring will return the second through end’th characters, or 't123'.
  • Once the statement providing the value to the third parameter is executed, cmp can return a value. At that point, strcat` can return a value, then ``substr can return a value. The program then terminates.

Für verschiedene Werte von series_index gibt das Programm Folgendes aus:

  • series_index == undefined, result = prefix ->t123 suffix
  • series_index == 0.5, result = prefix 0.50-> suffix
  • series_index == 1, result = prefix 1->t12 suffix
  • series_index == 2, result = prefix 2->eq suffix
  • series_index == 3, result = prefix 3->gt suffix

All the functions listed under single-function mode can be used in program mode. To do so, you must supply the value that the function is to act upon as the first parameter, in addition to the parameters documented above. For example, in program mode the parameters of the test function are test(x, text_if_not_empty, text_if_empty). The x parameter, which is the value to be tested, will almost always be a variable or a function call, often field().

The following functions are available in addition to those described in single-function mode. Remember from the example above that the single-function mode functions require an additional first parameter specifying the field to operate on. With the exception of the id parameter of assign, all parameters can be statements (sequences of expressions). Note that the definitive documentation for functions is available in the section Function classification:

  • and(Wert, Wert, …) – gibt die Zeichenkette „1“ zurück, falls alle Werte nicht leer sind, andernfalls wird eine leere Zeichenkette zurückgegeben. Diese Funktion arbeitet gut mit den Funktionen „test“ oder „first_non_empty“ zusammen. Sie können so viele Werte wie gewünscht angeben.

  • add(x, y) – Gibt x + y zurück. Löst einen Ausnahmefehler aus, falls x und/oder y keine Zahl ist.

  • assign(ID, Wert) – weist Wert der ID zu und gibt dann Wert zurück. ID muss ein Bezeichner sein, kein Ausdruck.

  • approximate_formats() – gibt eine kommagetrennte Liste von Formaten zurück, die zu einem bestimmten Zeitpunkt zu dem Buch gehörten. Es existiert keine Garantie, dass diese Liste korrekt ist, wahrscheinlich ist sie es allerdings. Diese Funktion kann im Vorlageprogrammmodus unter Verwendung der Vorlage {program:'approximate_formats()'} aufgerufen werden. Beachten Sie, dass Formatnamen immer aus Großbuchstaben bestehen, wie z. B. in „EPUB“.

  • author_links(Wertetrennzeichen, Paartrennzeichen) – gibt eine Zeichenkette zurück, die eine Liste von Autoren und den Verweiswerten der entsprechenden Autoren enthält, und zwar in der Form Autor1 `Wertetrennzeichen` Autor1Verweis `Paartrennzeichen` Autor2 `Wertetrennzeichen` Autor2Verweis . Ein Autor wird von dessen Verweiswert durch die Wertetrennzeichen-Zeichenkette ohne zusätzlichen Leerzeichen getrennt. Autor:Verweiswert-Paare werden durch die Paartrennzeichen-Zeichenkette ohne zusätzlichen Leerzeichen getrennt. Es liegt an Ihnen, Trennzeichen-Zeichenketten auszuwählen, die weder in Autorennamen, noch in Verweisen vorkommen. Ein Autor ist auch dann enthalten, falls der Autorenverweis leer ist.

  • author_sorts(Wertetrennzeichen) – gibt eine Zeichenkette zurück, die eine Liste von Autorensortierungswerten für die Autoren des Buchs enthält. Die Sortierung ist jene in den Autormetadaten (unterscheidet sich von der Autorensortierung in Büchern). Die zurückgegebene Liste besitzt die Form Autorensortierung1 `Wertetrennzeichen` Autorensortierung2 Die Autorensortierungswerte in dieser Liste besitzen die gleiche Reihenfolge wie die Autoren des Buches. Falls Sie Leerzeichen um das Wertetrennzeichen herum wollen, so schließen Sie diese in die Trennzeichen-Zeichenkette mit ein.

  • booksize() – gibt den Wert von Calibres Größenfeld zurück. Gibt ‚‘ zurück, falls keine Formate vorhanden sind.

  • cmp(x, y, kleiner_als, gleich, größer_als) – vergleicht x und y nach deren Konvertierung in Zahlenwerte. Gibt kleiner_als zurück, wenn x < y. Gibt gleich zurück, wenn x == y. Andernfalls wird größer_als zurückgegeben.

  • current_library_name() – gibt den letzten Namen im Pfad zur aktuellen Calibre-Bibliothek zurück. Diese Funktion kann im Vorlageprogrammmodus durch Verwendung der Vorlage {:'current_library_name()'} aufgerufen werden.

  • current_library_path() – gibt den Pfad zur aktuellen Calibe-Bibliothek zurück. Diese Funktion kann im Vorlageprogrammmodus durch Verwendung der Vorlage {:'current_library_path()'} aufgerufen werden.

  • days_between(Datum1, Datum2) – gibt die Anzahl der Tage zwischen Datum1 und Datum2 zurück. Die Zahl ist positiv, falls Datum1 größer als Datum2 ist, andernfalls negativ. Falls Datum1 und/oder Datum2 keine Kalenderdaten sind, wird eine leere Zeichenkette zurückgegeben.

  • divide(x, y) – Gibt x / y zurück. Löst einen Ausnahmefehler aus, falls x und/oder y keine Zahl ist.

  • eval(Zeichenkette) - wertet die Zeichenkette als ein Programm aus und gibt die lokalen Variablen (jene, die mittels der Funktion assign zugewiesen wurden) weiter. Dies erlaubt die Verwendung des Vorlagenprozessors zum Erstellen komplexer Ergebnisse aus lokalen Variablen. Da die „{„- und „}“-Zeichen Spezialfälle sind, müssen Sie „[[“ für „{“ und „]]“ für „}“ verwenden; diese werden automatisch umgewandelt. Beachten Sie, dass Präfixe und Suffixe (der Syntax |prefix|suffix) nicht innerhalb des Arguments dieser Funktion verwendet werden können, wenn der Vorlageprogrammmodus benutzt wird.

  • field(Name) – gibt das durch Name bezeichnete Metadatenfeld zurück.

  • first_matching_cmp(Wert, Vergleichswert1, Ergebnis1, Vergleichswert2, Ergebnis2, …, sonst_Ergebnis) – vergleicht nacheinander Wert < VergleichswertN und gibt für den ersten erfolgreichen Vergleich ErgebnisN zurück. Falls kein Vergleich erfolgreich ist, wird sonst_Ergebnis zurückgegeben. Beispiel:

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

    gibt „groß“ zurück. Dasselbe Beispiel mit einem ersten Wert von 16 gibt „riesig“ zurück.

  • first_non_empty(Wert, Wert, …) – gibt den ersten nicht leeren Wert zurück. Falls alle Werte leer sind, wird ein leerer Wert zurückgegeben. Sie können so viele Werte wie gewünscht angeben.

  • format_date(val, format_string) – format the value, which must be a date field, using the format_string, returning a string. The formatting codes are:

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

    You might get unexpected results if the date you are formatting contains localized month names, which can happen if you changed the format tweaks to contain MMMM. In this case, instead of using something like {pubdate:format_date(yyyy)}, write the template using template program mode as in {:'format_date(raw_field('pubdate'),'yyyy')'}.

  • finish_formatting(val, fmt, prefix, suffix) – apply the format, prefix, and suffix to a value in the same way as done in a template like {series_index:05.2f| - |- }. This function is provided to ease conversion of complex single-function- or template-program-mode templates to general program mode (see below) to take advantage of GPM template compilation. For example, the following program produces the same output as the above template:

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

    Another example: for the template {series:re(([^\s])[^\s]+(\s|$),\1)}{series_index:0>2s| - | - }{title} use:

    program:
        strcat(
            re(field('series'), '([^\s])[^\s]+(\s|$)', '\1'),
            finish_formatting(field('series_index'), '0>2s', ' - ', ' - '),
            field('title')
        )
    
  • formats_modtimes(Formatzeichenkette) – gibt eine kommagetrennte Liste von doppelpunktgetrennten Elementen zurück, welche die Änderungszeitpunkte für die Formate eines Buches darstellen. Der Parameter Formatzeichenkette gibt die Formatierung des Datums an. Siehe die Funktion format_date() für Details. Sie können die Funktion select verwenden, um den Änderungszeitpunkt für ein bestimmtes Format zu erhalten. Beachten Sie, dass Formatnamen immer aus Großbuchstaben bestehen, wie z. B. in „EPUB“.

  • formats_paths() – gibt eine kommagetrennte Liste von doppelpunktgetrennten Elementen zurück, welche den vollen Pfad zu den Formaten eines Buches darstellen. Sie können die Funktion select verwenden, um den Pfad für ein bestimmtes Format zu erhalten. Beachten Sie, dass Formatnamen immer aus Großbuchstaben bestehen, wie z. B. in „EPUB“.

  • formats_sizes() – gibt eine kommagetrennte Liste von doppelpunktgetrennten Elementen zurück, welche die Größen in Bytes der Formate eines Buches darstellen. Sie können die Funktion select verwenden, um die Größe für ein bestimmtes Format zu erhalten. Beachten Sie, dass Formatnamen immer aus Großbuchstaben bestehen, wie z. B. in „EPUB“.

  • has_cover() – gibt „Yes“ zurück, falls das Buch ein Titelbild besitzt, andernfalls wird eine leere Zeichenkette zurückgegeben.

  • not(Wert) – gibt die Zeichenkette „1“ zurück, falls der Wert leer ist, andernfalls wird eine leere Zeichenkette zurückgegeben. Diese Funktion arbeitet gut mit den Funktionen test oder first_non_empty zusammen.

  • list_difference(Liste1, Liste2, Trennzeichen) – gibt eine Liste zurück, die durch Entfernen jedes Elements von Liste1, das in Liste2 gefunden wird, unter Verwendung eines von Groß-/Kleinschreibung unabhängigen Vergleichs erstellt wird. Die Elemente in Liste1 und Liste2 werden durch Trennzeichen voneinander getrennt, ebenso wie die Elemente der zurückgegebenen Liste.

  • list_equals(Liste1, Trennzeichen1, Liste2, Trennzeichen2, ja_Wert, nein_Wert) – gibt ja_Wert zurück, falls Liste1 und Liste2 die gleichen Elemente enthalten, andernfalls wird nein_Wert zurückgegeben. Die Elemente werden durch Aufteilen jeder Liste unter Verwendung des entsprechenden Trennzeichens (Trennzeichen1 oder Trennzeichen2) bestimmt. Die Reihenfolge der Elemente in den Listen ist dabei irrelevant. Der Vergleich ignoriert die Groß-/Kleinschreibung.

  • list_intersection(Liste1, Liste2, Trennzeichen) – gibt eine Liste zurück, die durch Entfernen jedes Elements von Liste1, das in Liste2 nicht gefunden wird, unter Verwendung eines von Groß-/Kleinschreibung unabhängigen Vergleichs erstellt wird. Die Elemente in Liste1 und Liste2 werden durch Trennzeichen voneinander getrennt, ebenso wie die Elemente der zurückgegebenen Liste.

  • list_re(src_list, separator, include_re, opt_replace) – Construct a list by first separating src_list into items using the separator character. For each item in the list, check if it matches include_re. If it does, then add it to the list to be returned. If opt_replace is not the empty string, then apply the replacement before adding the item to the returned list.

  • list_re_group(src_list, separator, include_re, search_re, template_for_group_1, for_group_2, ...) – Like list_re except replacements are not optional. It uses re_group(item, search_re, template …) when doing the replacements.

  • list_sort(list, direction, separator) – return list sorted using a case-insensitive sort. If direction is zero, the list is sorted ascending, otherwise descending. The list items are separated by separator, as are the items in the returned list.

  • list_union(Liste1, Liste2, Trennzeichen) – gibt eine Liste zurück, die durch Zusammenführen der Elemente aus Liste1 und Liste2 erstellt wird, wobei Elementduplikate durch einen von Groß-/Kleinschreibung unabhängigen Vergleich entfernt werden. Falls sich Elemente in der Groß-/Kleinschreibung unterscheiden, wird das Element aus Liste1 verwendet. Die Elemente in Liste1 und Liste2 werden durch Trennzeichen voneinander getrennt, ebenso wie die Elemente der zurückgegebenen Liste.

  • multiply(x, y) – returns x * y. Throws an exception if either x or y are not numbers.

  • ondevice() – return the string „Yes“ if ondevice is set, otherwise return the empty string

  • or(value, value, ...) – returns the string „1“ if any value is not empty, otherwise returns the empty string. This function works well with test or first_non_empty. You can have as many values as you want.

  • print(a, b, ...) – prints the arguments to standard output. Unless you start calibre from the command line (calibre-debug -g), the output will go to a black hole.

  • raw_field(name) – returns the metadata field named by name without applying any formatting.

  • raw_list(name, separator) – returns the metadata list named by name without applying any formatting or sorting and with items separated by separator.

  • re_group(val, pattern, template_for_group_1, for_group_2, ...) – return a string made by applying the regular expression pattern to the val and replacing each matched instance with the string computed by replacing each matched group by the value returned by the corresponding template. The original matched value for the group is available as $. In template program mode, like for the template and the eval functions, you use [[ for { and ]] for }. The following example in template program mode looks for series with more than one word and uppercases the first word:

    {series:'re_group($, "(\S* )(.*)", "[[$:uppercase()]]", "[[$]]")'}
    
  • series_sort() – returns the series sort value.

  • strcat(a, b, ...) – can take any number of arguments. Returns a string formed by concatenating all the arguments.

  • strcat_max(max, string1, prefix2, string2, ...) – Returns a string formed by concatenating the arguments. The returned value is initialized to string1. Prefix, string pairs are added to the end of the value as long as the resulting string length is less than max. String1 is returned even if string1 is longer than max. You can pass as many prefix, string pairs as you wish.

  • strcmp(x, y, lt, eq, gt) – does a case-insensitive comparison x and y as strings. Returns lt if x < y. Returns eq if x == y. Otherwise returns gt.

  • strlen(a) – Returns the length of the string passed as the argument.

  • substr(str, start, end) – returns the start’th through the end’th characters of str. The first character in str is the zero’th character. If end is negative, then it indicates that many characters counting from the right. If end is zero, then it indicates the last character. For example, substr('12345', 1, 0) returns '2345', and substr('12345', 1, -1) returns '234'.

  • subtract(x, y) – returns x - y. Throws an exception if either x or y are not numbers.

  • today() – return a date string for today. This value is designed for use in format_date or days_between, but can be manipulated like any other string. The date is in ISO format.

  • template(x) – evaluates x as a template. The evaluation is done in its own context, meaning that variables are not shared between the caller and the template evaluation. Because the { and } characters are special, you must use [[ for the { character and ]] for the ‚}‘ character; they are converted automatically. For example, template('[[title_sort]]') will evaluate the template ``{title_sort} and return its value. Note also that prefixes and suffixes (the |prefix|suffix syntax) cannot be used in the argument to this function when using template program mode.

Funktionsklassifikation

Verwenden des Allgemeinen Programmmodus

For more complicated template programs, it is sometimes easier to avoid template syntax (all the { and } characters), instead writing a more classical-looking program. You can do this in calibre by beginning the template with program:. In this case, no template processing is done. The special variable $ is not set. It is up to your program to produce the correct results.

One advantage of program: mode is that the brackets are no longer special. For example, it is not necessary to use [[ and ]] when using the template() function. Another advantage is that program mode templates are compiled to Python and can run much faster than templates in the other two modes. Speed improvement depends on the complexity of the templates; the more complicated the template the more the improvement. Compilation is turned off or on using the tweak compile_gpm_templates (Compile General Program Mode templates to Python). The main reason to turn off compilation is if a compiled template does not work, in which case please file a bug report.

The following example is a program: mode implementation of a recipe on the MobileRead forum: „Put series into the title, using either initials or a shortened form. Strip leading articles from the series name (any).“ For example, for the book The Two Towers in the Lord of the Rings series, the recipe gives LotR [02] The Two Towers. Using standard templates, the recipe requires three custom columns and a plugboard, as explained in the following:

The solution requires creating three composite columns. The first column is used to remove the leading articles. The second is used to compute the ‚shorten‘ form. The third is to compute the ‚initials‘ form. Once you have these columns, the plugboard selects between them. You can hide any or all of the three columns on the library view:

First column:
Name: #stripped_series.
Template: {series:re(^(A|The|An)\s+,)||}

Second column (the shortened form):
Name: #shortened.
Template: {#stripped_series:shorten(4,-,4)}

Third column (the initials form):
Name: #initials.
Template: {#stripped_series:re(([^\s])[^\s]+(\s|$),\1)}

Plugboard expression:
Template:{#stripped_series:lookup(.\s,#initials,.,#shortened,series)}{series_index:0>2.0f| [|] }{title}
Destination field: title

This set of fields and plugboard produces:
Series: The Lord of the Rings
Series index: 2
Title: The Two Towers
Output: LotR [02] The Two Towers

Series: Dahak
Series index: 1
Title: Mutineers Moon
Output: Dahak [01] Mutineers Moon

Series: Berserkers
Series Index: 4
Title: Berserker Throne
Output: Bers-kers [04] Berserker Throne

Series: Meg Langslow Mysteries
Series Index: 3
Title: Revenge of the Wrought-Iron Flamingos
Output: MLM [03] Revenge of the Wrought-Iron Flamingos

The following program produces the same results as the original recipe, using only one custom column to hold the results of a program that computes the special title value:

Custom column:
Name: #special_title
Template: (the following with all leading spaces removed)
    program:
    #       compute the equivalent of the composite fields and store them in local variables
        stripped = re(field('series'), '^(A|The|An)\s+', '');
        shortened = shorten(stripped, 4, '-' ,4);
        initials = re(stripped, '[^\w]*(\w?)[^\s]+(\s|$)', '\1');

    #       Format the series index. Ends up as empty if there is no series index.
    #       Note that leading and trailing spaces will be removed by the formatter,
    #       so we cannot add them here. We will do that in the strcat below.
    #       Also note that because we are in 'program' mode, we can freely use
    #       curly brackets in strings, something we cannot do in template mode.
        s_index = template('{series_index:0>2.0f}');

    #       print(stripped, shortened, initials, s_index);

    #       Now concatenate all the bits together. The switch picks between
    #       initials and shortened, depending on whether there is a space
    #       in stripped. We then add the brackets around s_index if it is
    #       not empty. Finally, add the title. As this is the last function in
    #       the program, its value will be returned.
        strcat(
            switch( stripped,
                    '.\s', initials,
                    '.', shortened,
                    field('series')),
            test(s_index, strcat(' [', s_index, '] '), ''),
            field('title'));

Plugboard expression:
Template:{#special_title}
Destination field: title

It would be possible to do the above with no custom columns by putting the program into the template box of the plugboard. However, to do so, all comments must be removed because the plugboard text box does not support multi-line editing. It is debatable whether the gain of not having the custom column is worth the vast increase in difficulty caused by the program being one giant line.

User-defined template functions

You can add your own functions to the template processor. Such functions are written in Python, and can be used in any of the three template programming modes. The functions are added by going to Preferences -> Advanced -> Template functions. Instructions are shown in that dialog.

Besondere Hinweise für Speicher-/Sendevorlagen

Special processing is applied when a template is used in a save to disk or send to device template. The values of the fields are cleaned, replacing characters that are special to file systems with underscores, including slashes. This means that field text cannot be used to create folders. However, slashes are not changed in prefix or suffix strings, so slashes in these strings will cause folders to be created. Because of this, you can create variable-depth folder structure.

For example, assume we want the folder structure series/series_index - title, with the caveat that if series does not exist, then the title should be in the top folder. The template to do this is:

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

The slash and the hyphen appear only if series is not empty.

The lookup function lets us do even fancier processing. For example, assume that if a book has a series, then we want the folder structure series/series index - title.fmt. If the book does not have a series, then we want the folder structure genre/author_sort/title.fmt. If the book has no genre, we want to use ‚Unknown‘. We want two completely different paths, depending on the value of series.

Um das zu erreichen:
  1. Create a composite field (give it lookup name #AA) containing {series}/{series_index} - {title}. If the series is not empty, then this template will produce series/series_index - title.
  2. Create a composite field (give it lookup name #BB) containing {#genre:ifempty(Unknown)}/{author_sort}/{title}. This template produces genre/author_sort/title, where an empty genre is replaced with Unknown.
  3. Set the save template to {series:lookup(.,#AA,#BB)}. This template chooses composite field #AA if series is not empty, and composite field #BB if series is empty. We therefore have two completely different save paths, depending on whether or not series is empty.

Templates and plugboards

Plugboards are used for changing the metadata written into books during send-to-device and save-to-disk operations. A plugboard permits you to specify a template to provide the data to write into the book’s metadata. You can use plugboards to modify the following fields: authors, author_sort, language, publisher, tags, title, title_sort. This feature helps people who want to use different metadata in books on devices to solve sorting or display issues.

When you create a plugboard, you specify the format and device for which the plugboard is to be used. A special device is provided, save_to_disk, that is used when saving formats (as opposed to sending them to a device). Once you have chosen the format and device, you choose the metadata fields to change, providing templates to supply the new values. These templates are connected to their destination fields, hence the name plugboards. You can, of course, use composite columns in these templates.

When a plugboard might apply (Content server, save to disk, or send to device), calibre searches the defined plugboards to choose the correct one for the given format and device. For example, to find the appropriate plugboard for an EPUB book being sent to an ANDROID device, calibre searches the plugboards using the following search order:

  • a plugboard with an exact match on format and device, e.g., EPUB and ANDROID
  • a plugboard with an exact match on format and the special any device choice, e.g., EPUB and any device
  • a plugboard with the special any format choice and an exact match on device, e.g., any format and ANDROID
  • a plugboard with any format and any device

The tags and authors fields have special treatment, because both of these fields can hold more than one item. A book can have many tags and many authors. When you specify that one of these two fields is to be changed, the template’s result is examined to see if more than one item is there. For tags, the result is cut apart wherever calibre finds a comma. For example, if the template produces the value Thriller, Horror, then the result will be two tags, Thriller and Horror. There is no way to put a comma in the middle of a tag.

The same thing happens for authors, but using a different character for the cut, a & (ampersand) instead of a comma. For example, if the template produces the value Blogs, Joe&Posts, Susan, then the book will end up with two authors, Blogs, Joe and Posts, Susan. If the template produces the value Blogs, Joe;Posts, Susan, then the book will have one author with a rather strange name.

Plugboards affect the metadata written into the book when it is saved to disk or written to the device. Plugboards do not affect the metadata used by save to disk and send to device to create the file names. Instead, file names are constructed using the templates entered on the appropriate preferences window.

Helpful tips

Vielleicht finden Sie die folgenden Ratschläge hilfreich.

  • Create a custom composite column to test templates. Once you have the column, you can change its template simply by double-clicking on the column. Hide the column when you are not testing.
  • Templates can use other templates by referencing a composite custom column.
  • In a plugboard, you can set a field to empty (or whatever is equivalent to empty) by using the special template {}. This template will always evaluate to an empty string.
  • The technique described above to show numbers even if they have a zero value works with the standard field series_index.