mallspråket för calibre

Mallspråket för calibre används på olika ställen. Den används för att anpassa mappstruktur och filnamn när du sparar filer från calibre-biblioteket till hårddisken eller e-bokläsenheten. Det används också för att definiera ”virtuella” kolumner som innehåller data från andra kolumner och så vidare.

Det grundläggande mallspråket är enkelt men har kraftfulla avancerade funktioner. En mall består av text och namn i klamrar som sedan ersätts av motsvarande metadata från boken som bearbetas. Till exempel är standardmallen som används för att spara böcker till enheter i calibre:

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

För boken ”The Foundation” av ”Isaac Asimov” kommer det bli:

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

Snedstrecken är texter, vilka sätts in i mallen var de dyker upp. Till exempel om den mall är:

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

För boken ”The Foundation” av ”Isaac Asimov” kommer det bli:

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

You can use all the metadata fields available in calibre in a template, including any custom columns you have created, by using its ’lookup name’. To find the lookup name for a column (field) hover your mouse over the column header. Names for custom columns (columns you have created yourself) always have a # as the first character. For series type custom columns there is always an additional field named #seriesname_index that is the series index for that series. So if you have a custom series field named #myseries, there will also be a field named #myseries_index.

Förutom de kolumnbaserade fälten, kan du också använda:

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

If a book does not have a particular piece of metadata, the field in the template is replaced by the empty string for that book. Consider, for example:

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

Om en bok har en serie, kommer mallen att producera:

Asimov, Isaac/Foundation/Second Foundation 3

och om en bok inte har en serie:

Asimov, Isaac/Second Foundation

(calibre tar automatiskt flera snedstreck och inledande eller avslutande mellanslag).

Advancerad formatering

Du kan göra mer än bara enkel substitution med mallarna. Du kan också villkora inkludera text och anpassa hur den substituerade data formateras.

Först, villkorad inkluderad text. Det finns fall där du kanske vill ha text som visas i utmatning endast om ett fältet inte är tomt. Ett vanligt fall är series och series_index, var du vill antingen ingenting eller de två värdena med ett bindestreck mellan dem. calibre hanterar det här fallet med hjälp av en specialfältsyntax.

Anta till exempel att du vill använda mallen:

{series} - {series_index} - {title}

If the book has no series, the answer will be - - title. Most people would rather the result be simply title, without the hyphens. To do this, use the extended syntax {field:|prefix_text|suffix_text}. When you use this syntax, if field has the value SERIES then the result will be prefix_textSERIESsuffix_text. If field has no value, then the result will be the empty string (nothing); the prefix and suffix are ignored. The prefix and suffix can contain blanks. Do not use subtemplates (`{ … }`) or functions (see below) as the prefix or the suffix.

Med hjälp av denna syntax, kan vi lösa ovanstående serien problem med mallen:

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

De bindestreck inkluderas endast om boken har ett serieindex, vilket den kommer att få endast om den har en serie.

Observera: Du måste inkludera tecknet : om du vill använda ett prefix eller ett suffix. Du måste antingen använda inga |-tecken eller båda; med hjälp av någon, som i {field:| - }, är inte tillåtet. Det är OK att inte tillhandahålla någon text för den ena eller den andra, såsom i {series:|| - }. Att använda {title:||} är detsamma som att använda {title}.

Andra: formatering. Anta att du vill se till att series_index alltid är formaterad som tre siffror med inledande nollor. Detta bör göra susen:

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

Om istället för inledande noll vill ha inledande blankslag, använd:

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

För efterföljande nollor, använd:

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

Om du använder indexserien med undervärden (t.ex. 1.1), kanske du vill se till att decimaler kommer i följd. Till exempel kanske du vill att index 1 och 2,5 framstå som 01.00 och 02.50, så att de kommer att sorteras rätt. För att göra detta använd:

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

Om du vill bara ha de två första bokstäverna i uppgifterna, använd:

{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 <https://docs.python.org/library/string.html#format-string-syntax>.

Använd mallar i anpassade kolumner

Sometimes you want to display metadata in the book list 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}.

Sammansatta kolumner kan använda godtyckligt mallalternativ, även formatering.

You cannot edit the data displayed in a composite column. If you edit a composite column, for example by double-clicking it, 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.

Using functions in templates - Single Function Mode

Anta att du vill visa värdet på ett fält i versaler, då detta fält är normalt i rubrikformat. Du kan göra detta (och många fler saker) med hjälp av de funktioner som finns för mallar. Till exempel för att visa titeln med versaler, använd {title:uppercase()}. För att via det i rubrikformat använd {title:titlecase()}.

Functions 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 ().

Funktioner alltid tillämpas innan formatspecifikationer. Se längre ner för ett exempel på att använda både ett format och en funktion, där denna ordning demonstreras.

Syntaxen för att använda funktioner är {fält:funktion(argument)}, eller {fält:funktion(argument)|prefix|suffix}. Argument separeras med kommatecken. Komma inuti argument måste föregås av ett bakåtstreck ( \ ). Det sista (eller enda) argumentet får inte innehålla en avslutande parentes ( ) ). Funktioner återger värdet för fältet som används i mallen, lämpligt modifierat.

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.

Många funktioner använder reguljära uttryck. I samtliga fall är matchning med reguljära uttryck skiftlägeskänsliga.

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

  • lowercase() – återger värde av fältet som gemener.

  • uppercase() – återger värde av fältet som versaler.

  • titlecase() – återge värde av fältet som rubrikformat.

  • capitalize() – återge värde av fältet med första bokstav versal och övriga gemener.

  • contains(pattern, text if match, text if not match) – kollar om fältet innehåller träffar för det reguljära uttrycket pattern. Återger text vid träff om träff hittas annars återges text om ingen träff.

  • count(separator) – tolkar värde som en lista med poster åtskilda med separator, återger antalet poster i listan. De flesta listor använder kommatecken som avskiljare men författarna använder ett et-tecken. Exempel: {tags:count(,)}, {authors:count(&)}

  • format_number(mall) – tolkar fältet som ett tal och formaterar det numret med en Python formateringsmall som ”{0:5.2f}” eller ”{0:,d}” eller ”${0:5,.2f}”. Fältnamnsdelen (field_name) av mallen måste vara 0 (noll) (”{0:” i ovanstående exempel). Du kan lämna den ledande ”{0:” och efterföljande ”}” om mallen bara innehåller ett format. Se mallspråket och Python-dokumentationen för fler exempel. Återger den tomma strängen om formateringen misslyckas.

  • human_readable() – förväntar sig att värdet är ett nummer och återger en sträng som representerar det numret i kB, MB, GB, o.s.v.

  • ifempty(text) – Om fältet inte är tomt, återge värdet av fältet. annars återge text.

  • in_list(separator, pattern, found_val, ..., not_found_val) – behandla fältet som en lista med post åtskilda av separator, utvärdera mönstret mot varje värde i listan. Om mönstret matchar ett värde, återges found_val, annars återges not_found_val. Mönstret och found_value kan upprepas så många gånger som önskat, vilket möjliggör att olika värden återkommer beroende på sökningen. Mönstren kontrolleras i ordning. Den första matchen återges.

  • language_codes(lang_strings) – återger språkkoder för strängar som finns i lang_strings. Strängarna ska vara på samma språk som den aktuella platsen. Lang_strings är en kommaseparerad lista.

  • language_strings (lang_codes, lokalisera) – återger strängarna för de koder språk passerade i lang_codes. Om localize är noll, återger strängarna på engelska. Om lokalisera inte är noll, återger strängarna på språket på den aktuella platsen. Lang_codes är en kommaseparerad lista.

  • list_item(index, separator) – tolkar fältet som en lista med poster åtskilda med separator, återge` index`-posten. Den första elementet är siffran noll. Den sista punkten kan återges med list_item (-1, separator). Om elementet inte finns i listan, då återges det tomma värdet. Avskiljaren har samma betydelse som i count funktionen.

  • lookup(pattern, field, pattern, field, ..., else_field) – som switch-funktionen, förutom att argumenten är fältet (metadata) namn, inte text. Värdet på lämpligt fält att hämtas och används. Observera att eftersom sammansatta kolumnerna är fält, kan du använda den här funktionen i en sammansatt fält för att använda värdet av något annat sammansatt fält. Detta är mycket användbart när man konstruerar variabel spara sökvägar (mer senare).

  • rating_to_stars (use_half_stars) – Återger betygsättningen som sträng av stjärntecken. Källvärdet måste vara ett nummer mellan 0 och 5. Ställ in use_half_stars till 1 om du vill ha halvstjärntecken för anpassade betygskolumner som inte är heltal, till exempel 2.5.

  • re(pattern, replacement) – återger fältet efter applicering av reguljära uttryck. Alla förekomster av pattern ersätts med replacement. Som i alla calibre, är dessa Python-kompatibla reguljära uttryck.

  • select(key) – tolka fältet som en kommaseparerad lista över poster, med posterna som formen ”id:värde”. Hitta paret med id som är lika med nyckeln och återge motsvarande värde. Denna funktion är särskilt användbar för att extrahera ett värde som en ISBN från uppsättningen identifierare för en bok.

  • shorten(left chars, middle text, right chars) – Återge en förkortad version av fältet, som består av left chars tecken från början av fältet, följt av middle text, följt av höger chars tecken från slutet av strängen. Left chars och right chars måste vara heltal. Antag till exempel titeln på boken är Ancient English Laws in the Times of Ivanhoe, och du vill att den ska passa in i ett utrymme av högst 15 tecken. Om du använder {title:shorten(9, -, 5)}, kommer resultatet att bli Ancient E-nhoe. Om fältets längd är mindre än left chars + right chars + längden på middle text, då fältet kommer att användas intakt. Till exempel den i rubriken The Dome skulle inte ändras.

  • str_in_list(separator, string, found_val, ...,not_found_val) – behandlar fälten som en lista med post åtskilda av separator, jämför string mot varje värde i listan. Om string matchar ett värde (ignorerar versaler), återges found_val, annars återges not_found_val. Om strängen innehåller avskiljare, då behandlas det också som en lista och varje värde kontrolleras. string och found_value kan upprepas så många gånger som önskat, vilket möjliggör att olika värden återges beroende på sökningen. Strängarna kontrolleras i ordning. Den första träffen återges.

  • subitems(start_index, end_index) – Denna funktion används för att bryta isär listor över tagglika hierarkiska post såsom genrer. Det tolkar fältet som en kommaseparerad lista över taggliknande post, där varje post är en period separerad lista. Återger en ny lista görs genom att först hitta alla period separerad tagg liknande föremål, därefter för varje sådan post extrahera komponenterna från start_index till` end_index`, sedan kombinera resultaten tillbaka tillsammans. Den första komponenten i en period separerad lista har ett index på noll. Om ett index är negativ, så det räknas från slutet av listan. Som ett special fall är en END_INDEX av noll antas vara längden av listan. Exempel:

    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) – tolkar värden som en lista med post åtskilda med separator, återger en ny lista gjord av posterna från start_index till end_index. Den första punkten är siffran noll. Om ett index är negativ, så det räknas från slutet av listan. Som ett specialfall är en END_INDEX av noll antas vara längden av listan. Exempel om man antar att taggkolumnen (som är kommaseparerade) innehåller ”A, B ,C”:

    {tags:sublist(0,1,\,)} returns "A"
    {tags:sublist(-1,0,\,)} returns "C"
    {tags:sublist(0,-1,\,)} returns "A, B"
    
  • swap_around_articles(separator) – återger valet med artiklar flyttade till slutet. Värdet kan vara en lista, i vilket fall varje medlem av listan behandlas. Om värdet är en lista måste du ange listvärdesavskiljare. Om ingen avskiljare tillhandahålls behandlas värdet som ett enda värde, inte en lista.

  • swap_around_comma() – ges ett fält med ett värde av formen B, A, återges AB. Detta är mest användbart för att konvertera namnen i EN, FN format till FN EN. Om det inte finns någon kommatecken återges funktionen val oförändrad.

  • switch(pattern, value, pattern, value, ..., else_value) – för varje pattern, value par, kontrollerar om fältet matchar det reguljära uttrycket pattern och i så fall återger att value. Om inget pattern matchar, då återges else_value. Du kan ha så många pattern, value par som du vill.

  • test(text if not empty, text if empty) – återger text om inte empty om fältet inte är tomt, annars återges text om empty.

  • transliterate() – Återger en sträng i ett latinskt alfabet som bildas genom en tillnärmning av ljudet av orden i källfältet. Till exempel om källfältet är Фёдор Миха́йлович Достоевский återger funktionen Fiodor Mikhailovich Dostoievskii.’

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

Observera att du kan använda prefix och suffix också. Om du vill att numret ska visas som [003] eller [000], använd då fältet:

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

More complex functions in templates - Template Program Mode

Template Program Mode differs from Single Function Mode in that it permits writing template expressions that refer to other metadata fields, use nested functions, modify values, and do arithmetic. It is a reasonably complete programming language.

You can use the functions documented above in Template Program Mode. See below for details.

Beginning with an example, assume you want your template to show the series for a book if it has one, otherwise show the value of a custom field #genre. You cannot do this in the basic template language because you cannot make reference to another metadata field within a template expression. In Template Program Mode, you can. The following expression works:

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

Exemplet visar flera saker:

  • Template Program Mode is used if the expression begins with :' and ends with '. Anything else is assumed to be in single function mode.

  • variabeln $ står för fältet uttrycket fungerar på, #serier i detta fall.

  • funktioner måste få alla deras argument. Det finns inget standardvärde. Till exempel måste de inbyggda standard funktionerna ges en extra initial parameter som indikerar källfältet, vilket är en avsevärd skillnad från enkelfunktionsläge.

  • mellanslag ignoreras och kan användas var som helst i uttrycket.

  • konstanta strängar är inneslutna i matchande citat, antingen ' eller ``”` `.

The syntax of the language is shown by the following grammar. For a discussion of ’compare’,’if_expression’, and ’template_call’ see General Program Mode::

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

Kommentarer är rader med ett ”#” tecknet i början av raden.

An expression without errors always has a value. The value of an expression_list is the value of the last expression in the list. As such, the value of the program (expression_list):

1; 2; 'foobar'; 3

är 3.

Ett annat exempel på ett komplext men ganska dumt program kan bidra till att göra saker och ting tydligare:

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

Detta program gör följande:

  • specify that the field being looked at is series_index. The variable $ is set to its value.

  • anrop av substr funktionen, som tar 3 parametrar (str, start, slut) ``. Den återger en sträng som bildas genom att extrahera start genom sluttecken från strängen, nollbaserad (det första tecknet är tecknet noll). I detta fall strängen kommer att beräknas av ``strcat funktionen, är början 0, och slutet är 6. I detta fall den ger de 6 första tecknen i strängen som återges av strcat, vilket måste utvärderas innan substr kan återvända.

  • anropar strcat (strängsammanfogning) funktionen. Strcat accepterar 1 eller flera argument, och återger en sträng som bildas genom att sammanfoga alla värden. I detta fall finns det tre argument. Den första parametern är värdet i $, vilket här är värdet på series_index. Den andra parametern är en konstantsträng `` ’->’ . Den tredje parametern är värdet som återges av ``cmp funktionen, som ska vara fullt utvärderad innan strcat kan återge.

  • 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'.

  • När påståendet som ger värdet till den tredje parametern utförs, cmp kan ett värde återges. Vid den tidpunkten, kan strcat`  återge ett värde, ``substr kan återge ett värde. Programmet avslutas därefter.

Vid olika värden för series_index återger programmet:

  • series_index == odefinerad, 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 reference:

  • and(value, value, ...) – återger strängen ”1” om alla värdena inte är tomma, annars återges tomma strängen. Den här funktionen fungerar bra med testet eller first_non_empty. Du kan ha så många värden som du önskar.

  • add(x, y) – återger x + y. Ger ett undantag om någon av x eller y inte är tal.

  • assign(id, val) – tilldelar val till id, återger sedan val. id måste vara en identifierare, inte ett uttryck

  • approximate_formats() – return a comma-separated list of formats that at one point were associated with the book. There is no guarantee that the list is correct, although it probably is. This function can be called in Template Program Mode using the template {:'approximate_formats()'}. Note that format names are always uppercase, as in EPUB.

  • author_links(val_separator, pair_separator) – återger en sträng som innehåller en lista med författare och att författarens länkvärden i form author1 val_separator author1link pair_separator author2 val_separator author2link o.s.v. En författare är separerad från dess länk värde av val_separator sträng utan tillagda mellanslag. author:linkvalue paren skiljs åt av pair_separator strängargument utan tillagda mellanslag. Det är upp till dig att välja avskiljare som inte förekommer i författarnamn eller länkar. En författare ingår, även om författaren länken är tom.

  • author_sorts(val_separator) – återger en sträng med en lista med författarens sorteringsvärden för författarna till boken. Sorteringen är författarens metadata (som skiljer sig från den author_sort i böcker). Den återgivna listan har formen författaren sortera 1 val_separator författare sort 2 o.s.v. Författaren sortera värdena i denna lista är i samma ordning som författarna till boken. Om du vill ha mellanslag runt val_separator så inkludera dem i avskiljarsträngen

  • booksize() – återger värdet för den calibre ’storlek’ fält. Återger ’’ om det inte finns några format.

  • check_yes_no(field_name, is_undefined, is_false, is_true) – kontrollerar värdet på fältet ja/nej som heter genom sökningsnyckelens field_name för ett värde som anges av parametrarna, återger ”ja” om en matchning hittas, annars återges en tom sträng. Ställ in parametern is_undefined, is_false eller is_true till 1 (numret) för att kontrollera det villkoret, annars ställ in på 0. Exempel:

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

    återger ”ja” om fältet ja/nej "#bool" antingen är odefinierad (varken sann eller falsk) eller sann. Mer än en av is_undefined, is_false, eller is_true kan ställas in som 1. Den här funktionen används vanligtvis av funktionerna test() eller is_empty().

  • ceiling(x) – återger det minsta heltalet som är större än eller lika med x. Kaster ett undantag om x inte är ett tal.

  • cmp(x, y, lt, eq, gt) – jämför x och y efter konverterat både till siffror. Återger lt om x < y. Återger eq om x == y. Annars återges gt.

  • connected_device_name(storage_location) – if a device is connected then return the device name, otherwise return the empty string. Each storage location on a device can have a different name. The location names are ’main’, ’carda’ and ’cardb’. This function works only in the GUI.

  • connected_device_uuid(storage_location) – if a device is connected then return the device uuid (unique id), otherwise return the empty string. Each storage location on a device has a different uuid. The location names are 'main', 'carda' and 'cardb'. This function works only in the GUI.

  • current_library_name() – return the last name on the path to the current calibre library. This function can be called in Template Program Mode using the template {:'current_library_name()'}.

  • current_library_path() – return the path to the current calibre library. This function can be called in Template Program Mode using the template {:'current_library_path()'}.

  • days_between(date1, date2) – återge antalet dagar mellan date1 och date2. Numret är positivt om date1 är större än date2, annars negativt. Om någon date1 eller date2 inte är datum, återger funktionen tomma strängen.

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

  • eval(string) – evaluates the string as a program, passing the local variables (those assign ed to). This permits using the template processor to construct complex results from local variables. Because the { and } characters are special, you must use [[ for the { character and ]] for the ’}’ character; they are converted automatically. Note also that prefixes and suffixes (the |prefix|suffix syntax) cannot be used in the argument to this function when using Template Program Mode.

  • field(name) – återger metatdatafältet med nämnt efter name.

  • 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", " - ", " - ")
    

    Ytterligare exempel: för mallen {series:re(([^\s])[^\s]+(\s|$),\1)}{series_index:0>2s| - | - }{title} använd:

    program:
        strcat(
            re(field('series'), '([^\s])[^\s]+(\s|$)', '\1'),
            finish_formatting(field('series_index'), '0>2s', ' - ', ' - '),
            field('title')
        )
    
  • first_matching_cmp(val, cmp1, result1, cmp2, r2, ..., else_result) – jämför val < cmpN i sekvens, återger resultN för första jämförelsen som lyckas. Återger else_result om ingen jämförelse lyckas. Exempel:

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

    återger ”large”. Samma exempel med ett första värde på 16 återger ”giant”.

  • first_non_empty (värde, värde, ...) - återger det första värdet som inte är tomt. Om alla värden är tomma, då återges det tomma värdet. Du kan ha så många värden som du vill.

  • floor(x) – återger det största heltalet mindre än eller lika med x. Kaster ett undantag om x inte är ett tal.

  • format_date(val, format_string) – formatera värdet, vilket måste vara ett datumfält med hjälp av format_string, återsänder en sträng. Formateringskoder är:

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

  • formats_modtimes(format_string) – återger en kommaseparerad lista över kolonseparerade post som representerar modifieringstider för formaten i en bok. Den format_string parametern anger hur datumet ska formateras. Se format_date()-funktionen för detaljer. Du kan använda funktionen för val för att få modifieringstider för ett visst format. Observera att formatnamn är alltid versaler, som i EPUB.

  • formats_paths() – återger en kommaseparerad lista över kolonseparerade post som representerar fullständig sökväg till format i en bok. Du kan använda select-funktionen för att få sökvägen för ett visst format. Observera att formatnamn är alltid versaler, som i EPUB.

  • formats_sizes() – återger en kommaseparerad lista över kolonseparerade poster som representerar storlekar i oktetter av formaten i en bok. Du kan använda select-funktionen för att få storleken för ett visst format. Observera att formatnamn är alltid versaler, som i EPUB.

  • fractional_part(x) – returns the value after the decimal point. For example, fractional_part(3.14) returns 0.14. Throws an exception if x is not a number.

  • has_cover() – return Yes if the book has a cover, otherwise return the empty string.

  • not(value) – återger strängen ”1” om värdet är tomt, annars återges tomma strängen. Denna funktion fungerar bra med test eller first_non_empty.

  • list_difference(list1, list2, separator) – återge en lista genom att ta bort list1 alla post som finns i ”list2” med en skiftlägeskänslig jämförelse. Posterna i ”list1” och ”list2” skiljs åt av avskiljare, liksom posterna i den återgivna listan.

  • list_equals(list1, sep1, list2, sep2, yes_val, no_val) – återger yes_val om list1 och list2 innehåller samma poster, annars återges no_val. Föremålen bestäms genom att dela upp varje lista med lämpliga avgränsare (sep1 eller sep2). Ordningen på posterna i listorna inte är relevant. Jämförelsen är inte skiftlägeskänslig.

  • list_intersection(list1, list2, separator) – återge en lista genom att ta bort list1 alla post som finns i ”list2” med en skiftlägeskänslig jämförelse. Posterna i ”list1” och ”list2” skiljs åt av avskiljare, liksom posterna i den återgivna listan.

  • list_re(src_list, separator, include_re, opt_replace) – Konstruera en lista genom att först separera src_list i poster med tecknet separator. För varje post i listan, kolla om det matchar include_re. Om den gör det, lägg till den i listan som ska återges. Om opt_replace inte är den tomma strängen, så tillämpa bytet innan du lägger till posten till den återgivna listan.

  • list_re_group(src_list, separator, include_re, search_re, template_for_group_1, for_group_2, ...) – Liksom list_re utom ersättare inte är valbar. Den använder re_group (item, search_re, mall …) när man gör ersättning.

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

  • list_union(list1, list2, separator) – return a list made by merging the items in list1 and list2, removing duplicate items using a case-insensitive comparison. If items differ in case, the one in list1 is used. The items in list1 and list2 are separated by separator, as are the items in the returned list.

  • mod(x) – returns the remainder of x / y, where x, y, and the result are integers. Throws an exception if either x or y is not a number.

  • multiply(x, y) – återger x * y. Ger ett undantag om någon x eller y inte är tal.

  • 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, ...) – skriver ut argument till standard ut. Såvida du börjar calibre från kommandoraden (`` calibre-debug -g``), kommer utmatning att gå till ett svart hål.

  • raw_field(name) – återger metadatafält nämnt efter name utan att tillämpa någon formatering.

  • raw_list(name, separator) – återger listan metadata med namnet name utan att tillämpa någon formatering eller sortering och med poster åtskilda av avskiljare.

  • 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()]]", "[[$]]")'}
    
  • round(x) – återger närmaste heltal till x. Kaster ett undantag om x inte är ett tal.

  • series_sort() – återger seriens sorterade värden.

  • 'split(list_val, sep, id_prefix) – splits the list_val into separate values using sep, then assigns the values to variables named id_prefix_N where N is the position of the value in the list. The first item has position 0 (zero). The function returns the last element in the list. Example:

    split('one, two, foo', ',', 'var')
    

is equivalent to:

var_0 = 'one';
var_1 = 'two';
var_3 = 'foo
  • strcat(a, b, ...) – kan ta valfritt antal argument. Återger en sträng som bildas genom att sammanfoga alla argumenten.

  • 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. Returns string1 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) – Återger längden på strängen som skickas som argument.

  • substr(str, start, end) – återger start genom end tecknen i str. Det första tecknet i str är nolltecken. Om slutet är negativt, då det tyder på att många tecken räknat från höger. Om slutet är noll, då det tyder på det sista tecknet. Till exempel substr("12345", 1, 0) `` återger ``'2345' och substr('12345', 1, -1) återger '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.

Using General Program Mode

For more complicated template programs it is often easier to avoid template syntax (all the { and } characters), instead writing a more classic-looking program. You can do this by beginning the template with program:. The template program is compiled and executed. No template processing (e.g., formatting, prefixes, suffixes) is done. The special variable $ is not set.

One advantage of program: mode is that braces are no longer special. For example, it is not necessary to use [[ and ]] when using the template() function. Another advantage is readability.

Template Program Mode and General Program Mode support classic relational (comparison) operators: ==, !=, <, <=, >, >=. The operators return ’1’ if they evaluate to True, otherwise ’’. They do case-insensitive string comparison using lexical order. Examples:

  • program: field('series') == 'foo' returns ’1’ if the book’s series is ’foo’.

  • program: if field('series') != 'foo' then 'bar' else 'mumble' fi returns ’bar’ if the book’s series is not ’foo’, else ’mumble’.

  • program: if or(field('series') == 'foo', field('series') == '1632') then 'yes' else 'no' fi returns ’yes’ if series is either ’foo’ or ’1632’, otherwise ’no’.

  • program: if '11' > '2' then 'yes' else 'no' fi returns ’no’ because it is doing a lexical comparison. If you want numeric comparison instead of lexical comparison, use the operators ==#, !=#, <#, <=#, >#, >=#. In this case the left and right values are set to zero if they are undefined or the empty string. If they are not numbers then an error is raised.

Both General and Template Program Modes support ``if`` expressions with the following syntax:

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

The elif and else parts are optional. The words if, then, elif, else, and fi are reserved; you cannot use them as identifier names. You can put newlines and white space wherever they make sense. <<expression>> is one template language expression; semicolons are not allowed. <<expression_list>> is a semicolon-separated sequence of template language expressions, including nested ifs. Examples:

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

  • Nested if example:

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

An if produces a value like any other language expression. This means that all the following are valid:

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

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

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

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

The template language supports ``for`` expressions with the following syntax:

for <<id>> in <<expression>>:
    <<expression_list>>
rof

The expression must evaluate to either a metadata field lookup key, for example tags or #genre, or a comma-separated list of values. If the result is a valid lookup name then the field’s value is fetched, otherwise the list is broken into its individual values. Each resulting value in the list is assigned to the variable id then the expression_list is evaluated.

Example: This template removes the first hierarchical name for each value in Genre (#genre), constructing a list with the new names:

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

If the original Genre is History.Military, Science Fiction.Alternate History, ReadMe then the template returns Military, Alternate History, ReadMe. You could use this template in calibre’s Edit metadata in bulk  →  Search & replace with Search for set to template to strip off the first level of the hierarchy and assign the resulting value to Genre.

Note: the last line in the template, new_tags, isn’t necessary in this case because for returns the value of the last expression in the expression list.

Stored General Program Mode Templates

General Program Mode supports saving templates and calling those templates from another template. You save templates using Preferences → Advanced → Template functions. More information is provided in that dialog. You call a template the same way you call a function, passing positional arguments if desired. An argument can be any expression. Examples of calling a template, assuming the stored template is named foo:

  • foo() – call the template passing no arguments.

  • foo(a, b) call the template passing the values of the two variables a and b.

  • foo(if field('series') then field('series_index') else 0 fi) – if the book has a series then pass the series_index, otherwise pass the value 0.

In the stored template you retrieve the arguments passed in the call using the arguments function. It both declares and initializes local variables, effectively parameters. The variables are positional; they get the value of the value given in the call in the same position. If the corresponding parameter is not provided in the call then arguments assigns that variable the provided default value. If there is no default value then the variable is set to the empty string. For example, the following arguments function declares 2 variables, key, alternate:

arguments(key, alternate='series')

Examples, again assuming the stored template is named foo:

  • foo('#myseries') – argument key will have the value myseries and the argument alternate will have the value series.

  • foo('series', '#genre') the variable key is assigned the value series and the variable alternate is assigned the value #genre.

  • foo() – the variable key is assigned the empty string and the variable alternate is assigned the value #genre.

An easy way to test stored templates is using the Template tester dialog. Give it a keyboard shortcut in Preferences → Advanced → Keyboard shortcuts → Template tester. Giving the Stored templates dialog a shortcut will help switching more rapidly between the tester and editing the stored template’s source code.

Providing additional information to templates

A developer can choose to pass additional information to the template processor, such as application-specific book metadata or information about what the processor is being asked to do. A template can access this information and use it during the evaluation.

Developer: how to pass additional information

The additional information is a python dictionary containing pairs variable_name: variable_value where the values should be strings. The template can access the dict, creating template local variables named variable_name containing the value variable_value. The user cannot change the name so it is best to use names that won’t collide with other template local variables, for example by prefixing the name with an underscore.

This dict is passed to the template processor (the formatter) using the named parameter global_vars=your_dict. The full method signature is:

def safe_format(self, fmt, kwargs, error_value, book,

column_name=None, template_cache=None, strip_results=True, template_functions=None, global_vars={})

Template writer: how to access the additional information

You access the additional information in a template using the template function globals(id[=expression] [, id[=expression]]*) where id is any legal variable name. This function checks whether the additional information provided by the developer contains the name. If it does then the function assigns the provided value to a template local variable with the given name. If the name is not in the additional information and if an expression is provided, the expression is evaluated and the result is assigned to the local variable. If neither a value nor an expression is provided, the function assigns the empty string ('') to the local variable.

Notes on the difference between modes

The three program modes, Single Function Mode (SFM), Template Program Mode (TPM), and General Program Mode (GPM), work differently. SFM is intended to be ’simple’ so it hides a lot of programming language bits. For example, the value of the column is always passed as an ’invisible’ first argument to a function included in the template. SFM also doesn’t support the difference between variables and strings; all values are strings.

Example: the following SFM template returns either the series name or the string ”no series”:

{series:ifempty(no series)}

The equivalent template in TPM is

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

The equivalent template in GPM is:

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

The first argument to ifempty is the value of the field series. The second argument is the string no series. In SFM the first argument, the value of the field, is automatically passed (the invisible argument).

Several template functions, for example booksize() and current_library_name(), take no arguments. Because of the ’invisible argument’ you cannot use these functions in SFM.

Nested functions, where a function calls another function to compute an argument, cannot be used in SFM. For example this template, intended to return the first 5 characters of the series value uppercased, won’t work in SFM:

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

TPM and GPM support nested functions. The above template in TPM would be:

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

In GPM it would be:

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

Användardefinierade Python-mallfunktioner

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

Särskilda anvisningar för att spara/skicka mallar

Särskild bearbetning tillämpas när en mall används i en ’spara på disk` eller skicka till enhet mall. Värdena på fälten städas, ersätter tecken som är speciella till filsystem med understreck, inklusive snedstreck. Det innebär att textfältet inte kan användas för att skapa mappar. Snedstreck ändras dock inte i prefix eller suffixsträngar, så snedstreck i dessa strängar kommer att orsaka att mappar skapas. På grund av detta kan du skapa variabeldjup mappstruktur.

Antag till exempel att vi vill ha mappstrukturen series/series_index - title, med förbehållet att om serien inte existerar, så bör titeln vara i topp-mappen. Mallen för att göra detta är:

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

Det snedstreck och bindestreck visas bara om serien inte är tom.

Uppslagsfunktionen låter oss göra ännu snyggare bearbetning. Antag till exempel att om en bok har en serie, så vi vill att mappstrukturen series/series index - title.fmt. Om boken inte har en serie, så vi vill att mappstrukturen genre/author_sort/title.fmt. Om boken inte har någon genre, vill vi använda ’Okänd’. Vi vill två helt olika vägar, beroende på värdet av serien.

För att åstadkomma detta, vi:
  1. Skapa en sammansatt fält (ge det uppslagsnamn #AA) som innehåller {series}/{series_index} - {title'}. Om serien inte är tom, så kommer den här mallen att producera series/series_index - title.

  2. Skapa en sammansatt fält (ge det uppslagsnamn #BB) som innehåller``{#genre:ifempty(Unknown)}/{author_sort}/{title}``. Denna mall ger genre/author_sort/title, där en tom genre ersätts med Okänd.

  3. Ändra spara mallen till {series:lookup(.,#AA,#BB)}. Denna mall väljer sammansatta fält #AA om serien inte är tom, och sammansatta fält #BB om serien är tom. Vi har alltså två helt olika sparvägar, beroende på om eller inte series är tom.

Mallar och pluggbrädor

Pluggbrädor används för att ändra metadata som skrivs in böcker under ”skicka till enhet” och ”spara till disk” operationer. En pluggbräda tillåter dig att ange en mall för att tillhandahålla data som ska skrivas i bokens metadata. Du kan använda pluggbrädor för att ändra följande fält: författare, author_sort, språk, förläggare, taggar, titel, title_sort. Den här funktion hjälper personer som vill använda olika metadata i böcker på enheter för att lösa sortering- eller visningsproblem.

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.

När en pluggbräda kan gälla (Innehållsserver, spara till disk, eller skicka till enhet), söker calibre de definierade pluggbrädor att välja den rätta för givet format och enhet. Till exempel för att hitta rätt pluggbräda för en EPUB-bok som skickas till en Android-enhet, söker calibre dessa pluggbrädor enligt följande sökordning:

  • en pluggbräda med en exakt matchning på format och enhet, till exempel EPUB och ANDROID

  • en pluggbräda med en exakt matchning på format och den speciella any device val, till exempel `` EPUB`` och any device

  • en pluggbräda med en exakt matchning på format och den speciella any device val, och ANDROID

  • en pluggbräda med något format och någon enhet

Tagg och författar fält har särskild behandling, eftersom båda dessa fält kan ha mer än en post. En bok kan ha många taggar och många författare. När du anger att ett av dessa två fält ska ändras, är mallens resultat som undersöks för att se om mer än en post finns. För taggar, skärs resultatet bort varhelst calibre finner ett kommatecken. Till exempel om mallen producerar värdet Thriller, Horror, då blir resultatet två taggar, Thriller och Horror. Det finns inget sätt att sätta ett kommatecken i mitten av en tagg.

Samma sak händer för författare, men med en annan karaktär för snittet, en & (et-tecken) istället för ett kommatecken. Till exempel om mallen producerar värdet Blogs, Joe&Posts, Susan, då kommer boken att sluta med två författare, Blogs, Joe och Posts, Susan. Om mallen producerar värdet Blogs, Joe;Posts, Susan, då kommer boken att ha en författare med ett ganska konstigt namn.

Pluggbrädor påverkar metadata som skrivs in i boken när den sparas till disk eller skrivs till enheten. Pluggbrädor påverkar inte metadata som används av spara till disk och skicka till enhet för att skapa filnamnen. Istället konstrueras filnamn med hjälp av mallar som anges i lämpliga inställningsfönster.

Tips

Du kan hitta följande tips användbart.

  • Use the Template Tester to test templates. Add the tester to the context menu for books in the library and/or give it a keyboard shortcut.

  • Templates can use other templates by referencing composite columns built with the desired template. Alternatively, you could use Stored Templates.

  • I en kontrolpanel, kan du ställa in ett fält för att vara tomt (eller vad som motsvarar tom) med hjälp av särskild mall {}. Denna mall kommer alltid utvärderas till en tom sträng.

  • Den teknik som beskrivs ovan för att visa siffror även om de har ett nollvärde fungerar med standardfält series_index.

Function reference