calibre-mallspråket

calibre-mallspråket 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.

Den grundläggande mallspråket är mycket enkelt, men har mycket kraftfulla avancerade funktioner. Grundtanken är att en mall består av text och namnen i klammer som sedan ersätts av motsvarande metadata från boken som bearbetas. Så, till exempel, är standardmallen som används för att spara böcker till enheten 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

Du kan använda alla de olika metadatafält som finns i calibre i en mall, inklusive eventuella anpassade kolumner du har skapat själv. För att ta reda på mallnamnet för en kolumn håll bara musen över kolumntiteln. Namn för anpassade fält (kolumner du har skapat själv) har alltid en # som första tecken. För egna fält av serietyp , det finns alltid ett extra fält som heter #serienamn_index som blir serieindex för den serien. Så om du har ett eget seriefält som heter #minaserier, kommer det också att finnas ett fält som heter #minaserier_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

Om en viss bok inte har en särskild bit av metadata, avlägsnas automatiskt fältet i mallen för den boken. Tänk till exempel:

{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 blanksteg).

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

Om boken inte har någon serie, kommer svaret att vara - - title. Många människor skulle hellre vilja att resultatet blir helt enkelt title, utan bindestreck. För att göra detta, använd den utökade syntaxen `{field:|prefix_text|suffix_text}. När du använder den här syntaxen, om fältet har värdet SERIER kommer resultatet då att bli prefix_textSERIERsuffix_text. Om fältet inte har något värde, då kommer resultatet att vara den tomma strängen (ingenting); prefixet och suffixet ignoreras. Prefixet och suffixet kan innehålla blanksteg. Använd inte subtemplates(`{ … }`) eller funktioner (se nedan) som prefix eller 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: tecken om du vill använda ett prefix eller ett suffix. Du måste antingen använda några | tecken eller båda; med hjälp av någon, som i {field:| - }, är inte tillåtet. Det är OK att inte ge någon text för den ena eller den andra, såsom i {series:|| - }. 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

calibre-mallspråket kommer från Python och för mer information om syntaxen för dessa avancerade formaterings operationer, titta på Python dokumentation.

Avancerade funktioner

Använd mallar i anpassade kolumner

Ibland finns det fall där man vill visa metadata som calibre normalt inte visar, eller för att visa data på ett sätt som skiljer sig från hur calibre gör normalt. Till exempel kanske du vill visa ISBN, ett fält som calibre inte visar. Du kan använda anpassade kolumner för detta genom att skapa en kolumn med typen ”Kolumn byggs från andra kolumner” (nedan kallade sammansatta kolumner), och går in i en mall. Resultat: calibre kommer att visa en kolumn som visar resultatet av utvärderingen av den mallen. För att visa ISBN skapa kolumnen och skriv `` {identifierare: välj (isbn)} `` in i mallrutan. För att visa en kolumn som innehåller värdena för två serier anpassade kolumner separerade med ett kommatecken, använd {#serier1:||,}{#serier2}.

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

Du kan inte ändra uppgifterna i en sammansatt kolumn. Om du redigerar en sammansatt kolumn genom att dubbelklicka på ett objekt, kommer du öppna mallen för redigering, inte de underliggande data. Redigera mallen på gränssnittet är ett snabbt sätt att testa och ändra sammansatta kolumner.

Använda funktioner i mallar - enkelfunktionsläge

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

Funktionsreferenser återfinns i den del format, som går efter : och för första | eller avslutande }. Om du har både ett format och en funktionsreferens, kommer funktionen efter den andra :. Funktioner måste alltid avslutas med (). Några funktioner använder extra värden (argument) och dessa ska finnas i ().

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 returnerar 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.

De funktioner som finns är listade nedan. Observera att den slutgiltiga dokumentationen för funktioner finns i avsnitt Funktionsklassificering:

  • 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 objekt åtskilda med separator, återger antalet objekt i listan. De flesta listor använder kommatecken som skiljetecken, 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. Returnerar 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 objekt å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) – återge språkkoder för strängar passerade 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 objekt åtskilda med separator, återge` index` objektet. 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. Separatorn 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).

  • 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) – tolkar fält som en kommaseparerad lista med objekten är av formen ”id:värde”. Hitta det par med id lika med nyckel, och återge motsvarande värde. Den här funktionen är särskilt användbar för att extrahera ett värde såsom ett isbn från uppsättningen av identifierare för en bok.

  • shorten(left chars, middle text, right chars) – Återge en förkortad version av fältet, som består av vänster chars tecken från början av fältet, följt av mellan text, följt av höger chars tecken från slutet av strängen. Vänster chars och höger chars måste vara heltal. Antag till exempel titeln på boken är Ancient English Lagar i 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 vänster chars + höger chars + längden på mellan text, då fältet kommer att användas intakt. Till exempel, den i rubriken ’Domen` skulle inte ändras..

  • str_in_list(separator, string, found_val, ...,not_found_val) – behandlar fälten som en lista med objekt å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 separatorer, 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 matchen återges.

  • subitems(start_index, end_index) – Denna funktion används för att bryta isär listor över tagglika hierarkiska objekt såsom genrer. Det tolkar fältet som en kommaseparerad lista med taggliknande objekt, där varje objekt är en period separerad lista. Ger 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 objekt åtskilda med separator, återvänder en ny lista gjord av objekten 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_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.’

Nu, hur är det med funktioner och formatering inom samma fält. Anta att du har en heltalsanpassad kolumn kallad #myint som du vill se med ledande nollor, som i 003. För att göra detta, skulle du använda ett format på 0>3s. Men som standard, om ett nummer (heltal eller flyttal) är lika med noll då producerar fältet tomt värde, så nollvärden kommer att producera någonting, inte 000. Om du verkligen vill se 000 värden, då använder du både formatsträngen och ifempty funktionen för att ändra det tomma värdet till noll. Fältreferens vore:

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

bservera 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)|[|]}

Använda funktioner i mallar - mallprogramläge

Mallens språk för programläge skiljer sig från enkelfunktionsläge genom att den tillåter dig att skriva malluttryck som refererar till andra metadatafält, ändra värden och utföra aritmetik. Det är en ganska komplett programmeringsspråk.

Du kan använda de funktioner som dokumenterats ovan i mallprogramsläge. Se nedan för mer information.

Från och med ett exempel, anta att du vill att din mall visar serien för en bok om den har en, annars visar värdet av ett anpassat fält #genre. Du kan inte göra det i den grundläggande språket eftersom du inte kan hänvisa till en annan metadatafält i ett malluttryck. I programläget kan du. Följande uttryck fungerar:

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

Exemplet visar flera saker:

  • programläge används om uttrycket börjar med :' och slutar med '. Något annat antas vara enkelfunktion.
  • 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 funktioner ges en extra initial parameter som indikerar källfältet, vilket är en avsevärd skillnad från enkelfunktionsläge.
  • blanksteg ignoreras och kan användas var som helst i uttrycket.
  • konstanta strängar är inneslutna i matchande citat, antingen ' eller ``”` `.

Språket liknar funktionella språk genom att det är byggt nästan helt från funktioner. En förklaring är en funktion. Ett uttryck är en funktion. Konstanter och kännetecken kan ses som funktioner som återger värdet indikeras av konstanten eller lagrad i identifieraren.

Syntaxen för språket visas med följande grammatik:

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

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

Ett uttryck har alltid ett värde, antingen värdet på konstanten, det värde som finns i identifierare, eller det värde som återges av en funktion. Värdet av ett ’’påstående`` är värdet av det sista uttrycket i sekvensen av påståendet. Som sådan, värdet av programmet (påstående):

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:

  • ange att det fält som betraktas på är series_index. Detta ställer in värdet på variabeln ``$ ``.
  • 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.
  • ` cmp`` funktionen tar 5 argument (x, y, lt, eq, gt). Den jämför x och y och återger det tredje argumentet lt om x<y, den fjärde argumentet eq om x == y, och den femte argumentet gt om x>y. Som med alla funktioner kan alla parametrar vara påstående. I detta fall är den första parametern (värdet för x) är resultatet av att dividera series_index med 2. Den andra parametern y är konstant `` 1``. Den tredje parametern lt är ett påstående (mer senare). Den fjärde parametern eq är konstantsträngen 'eq'.. Den femte parametern är konstant sträng 'gt'.
  • Den tredje parametern (en för lt) är ett påstående, eller en sekvens av uttryck. Tänk på att ett påstående (en sekvens av semikolonseparerade uttryck) är också ett uttryck, återger värdet för det sista uttrycket i listan. I detta fall tilldelar programmet först värdet 1 till en lokal variabel c återger sedan en delsträng genom att extrahera c’th karaktär till slutet. Sedan c innehåller alltid konstant 1, delsträngen kommer den andra återge genom end’th tecknet, eller '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

Alla funktioner som listas under enkelfunktionsläge kan användas i programläge. För att göra det måste du ange det värde som funktionen ska verka på som första parameter, utöver de parametrar som dokumenterats ovan. Till exempel i programläge är parametrarna i test funktionen test(x, text_if_not_empty, text_if_empty). x parametern, vilket är det värde som ska testas, kommer nästan alltid att vara en variabel eller ett funktionsanrop, ofta field().

Följande funktioner finns tillgängliga utöver de som beskrivs i enkelfunktionsläge. Minns från exemplet ovan att enkelfunktionsläges funktionerna kräver att ytterligare första parameter anges för vilket fält som ska användas. Med undantag för id parametertilldelning, kan alla parametrar vara satser (sekvenser av uttryck). Observera att den slutgiltiga dokumentationen för funktioner finns i avsnittet Funktionsklassificering:

  • 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() – återger en kommaseparerad lista med format som vid ett tillfälle var förknippade med boken. Det finns ingen garanti att listan är korrekt, även om den antagligen är det. Denna funktion kan anropas i mallprogramläge med mallen {:'approximate_formats()'}. Observera att formatnamn är alltid versaler, som i 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 blanksteg. author:linkvalue paren skiljs åt av pair_separator strängargument utan tillagda blanksteg. Det är upp till dig att välja skiljesträngar 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 blanksteg runt val_separator så inkludera dem i avsiljarsträngen

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

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

  • current_library_name() – återge efternamnet på sökvägen till det nuvarande calibre-biblioteket. Denna funktion kan anropas i mallprogramläge genom att använda mallen {:'current_library_name()'}.

  • current_library_path() – återger sökvägen till det aktuella calibre-biblioteket. Denna funktion kan anropas i mallprogramläge med mallen {:'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) – återger x / y. Ger ett undantag om antingen x eller y inte är siffror.

  • eval(string) – utvärderar strängen som ett program, som skickar de lokala variabler (de assign ade till). Detta gör det möjligt att använda mallprocessorn för att konstruera komplexa resultat från lokala variabler. Eftersom {- och }-tecken är speciella, måste du använda [[ för {-tecknet och ]] för ’}’-tecknet; de konverteras automatiskt. Observera också att prefix och suffix (|prefix|suffix syntax) inte kan användas i argumentet till funktionen när du använder mallprogramläge.

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

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

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

    Du kan få oväntade resultat om det datum du formaterar innehåller lokaliserade månadsnamn, vilket kan hända om du ändrade formatjusteringar att innehålla MMMM. I detta fall, istället för att använda något i stil med {pubdate:format_date(yyyy)}, skriv mallen med mallprogramläge som i {:'format_date(raw_field('pubdate'),'yyyy')'}

  • finish_formatting(val, fmt, prefix, suffix) – tillämpa format, prefix och suffix till ett värde på samma sätt som görs i en mall som {series_index:05.2f| - |- }. Denna funktion finns för att underlätta konverteringen av komplexa enkelfunktions- eller mallprogrammods mallar till allmänna programläge (se nedan) för att dra nytta av GPM-mallkompilering. Till exempel ger följande program på samma utdata som ovanstående mall:

    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')
        )
    
  • formats_modtimes(format_string) – återger en kommaseparerad lista med kolonseparerade objekt 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 med kolonseparerade objekt 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 med 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.

  • has_cover() – återger Yes om boken har ett omslag annars återges tom sträng

  • 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 objekt som finns i list2 med en skiftlägeskänslig jämförelse. Objekten i list1 och list2 skiljs åt av separator, liksom de artiklar 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å objekten 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 objekt som finns i list2 med en skiftlägeskänslig jämförelse. Objekten i list1 och list2 skiljs åt av separator, liksom de artiklar i den återgivna listan.

  • list_re(src_list, separator, include_re, opt_replace) – Konstruera en lista genom att först separera src_list in poster med separator tecken. För varje post i listan, kolla om det matchar include_re. Om den gör det, så lägga 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) – återger lista sorterad med hjälp av en skiftlägeskänslig sortering. Om direction är noll, är listan sorteras stigande, annars fallande. Listposter är separerade med separator, likasom de poster i den återgivna listan.

  • list_union(list1, list2, separator) – återge en lista som görs av en sammanslagning av poster i list1 och list2, ta bort dubbletter med en skiftlägeskänslig jämförelse. Om objekt skiljer sig i fallet är den i list1 används. Objekten i list1 och list2 skiljs åt av separator, liksom de artiklar i den återgivna listan.

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

  • ondevice() – återger strängen ”Yes” om ondevice ställs in, annars återges den tomma strängen

  • or(value, value, ...) – återger strängen ”1”, om något värde inte är tomt, annars återges den tomma strängen. Den här funktionen fungerar bra med test eller first_non_empty. Du kan ha så många värden som du önskar.

  • print(a, b, ...) – skriver ut argument till standard ut. Såvida du börjar calibre från kommandoraden (`` calibre-debug -g``), kommer utdata 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 separator.

  • re_group(val, pattern, template_for_group_1, for_group_2, ...) – återger en sträng med användande av reqular uttrycksmönstret för val och ersätter varje matchande instans med strängen beräknad genom att ersätta varje matchande grupp med värdet som återges av motsvarande mall. Det ursprungliga matchande värdet för gruppen finns som $. I mallprogramläge, som till mallen och de eval funktioner använder du [[ för { och ]] för }. Följande exempel på mallprogramläge letar efter serie med mer än ett ord och sätter det första ordet till versaler:

    {series:'re_group($, "(\S* )(.*)", "[[$:uppercase()]]", "[[$]]")'}
    
  • series_sort() – återger seriens sorterade värden.

  • 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, ...) – Återger en sträng som bildas genom att sammanlänka argumenten. Det återgivna värdet initieras till string1. Prefix, string par som läggs till i slutet av värde så länge den resulterande strängens längd är mindre än max. String1 återges även om string1 är längre än max. Du kan skicka så många prefix, string par som du vill.

  • strcmp(x, y, lt, eq, gt) – gör en skiftlägesokänslig jämförelse x och y som strängar. Återger lt om x < y. Återge eq om x == y. Annars återge 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) – återger x - y. Ger ett undantag om någon x eller y inte är tal.

  • today() – återger en datumsträng för idag. Detta värde är konstruerad för användning i format_date eller days_between, men kan manipuleras precis som alla andra strängar. Datumet är i ISO format.

  • template(x) – utvärderar x som mall. Bedömningen görs i en egen kontext, vilket innebär att variabler inte delas mellan den som anropar och utvärderingsmallen. Eftersom {- och }-tecken är speciella, måste du använda [[ för {-tecknet och ]] för ’}’-tecknet; de konverteras automatiskt. Till exempel, template('[[title_sort]]') kommer att utvärdera mallen ``{title_sort} och återge dess värde. Observera också att prefix och suffix (det så kallade |prefix|suffix syntax) inte kan användas i argumentet till funktionen när du använder mallprogramläge.

Funktionsklassificering

Använder allmän programmod

För mer komplicerade mallprogram, är det ibland lättare att undvika mallsyntax (alla { och } tecken), istället skriva i ett mer klassisk programutseende. Du kan göra detta i calibre genom att börja mallen med program:. I detta fall sker ingen mall behandling. Den speciella variabeln $ är inte inställt. Det är upp till ditt program för att producera rätt resultat.

En fördel med program: läget är att hakparanteser inte längre speciella. Till exempel är det inte nödvändigt att använda [[ och ]] ’när du använder `template()-funktionen. En annan fördel är att programläges mallar sammanställs till Python och kan köras mycket snabbare än mallar i de andra två lägena. Hastighetsförbättring beror på komplexiteten i de mallar; ju mer komplicerad mall desto förbättringen. Kompileringen är avstängd eller om du använder justering compile_gpm_templates (Compile General Programläges mallar till Python). Det främsta skälet för att stänga av kompilering är om en sammanställd mall inte fungerar, i sådant fall skicka in en felrapport.

Följande exempel är ett ’program:` läge implementerande av ett recept på MobileRead forumet:”. Placera serier i titeln, antingen med initialer eller en förkortad form Strip ledande artiklar från serienamnet (någon). ”Till exempel, för boken The Two Towers in the Lord of the Rings-serien, ger receptet LotR [02] The Two Towers. Genom att använda standardmallar, receptet kräver tre anpassade kolumner och en pluggbräda, såsom förklaras i följande:

Lösningen kräver att skapa tre sammansatta kolumner. Den första kolumnen används för att avlägsna de ledande artiklarna. Det andra används för att beräkna den ”korta” formen. Den tredje är för att beräkna ’initials’ formen. När du har dessa kolumner, väljer pluggbräda mellan dem. Du kan dölja någon eller alla av de tre kolumnerna på biblioteksvyn.

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

Följande program ger samma resultat som det ursprungliga receptet, med endast en anpassad kolumn för att hålla resultatet av ett program som beräknar den speciella titelvärdet:

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

Det skulle vara möjligt att göra ovanstående utan extra kolumner genom att sätta programmet i mallrutan av pluggbrädan. Men för att göra det, måste alla kommentarer tas bort på grund av att pluggbrädans textrutan inte stöder redigering över flera rader. Det kan diskuteras om vinsten av att inte ha den anpassade kolumnen är värd den stora ökningen i svårigheter på grund av det program som en gigantisk rad.

Användardefinierade mallfunktioner

Du kan lägga till egna funktioner till mallprocessorn. Sådana funktioner är skrivna i Python, och kan användas i någon av de tre mallprogrammeringslägena. Funktionerna läggs till genom att gå till Inställningar->Avancerat->Mallfunktioner. Instruktioner visas i denna 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 de uppgifter att skriva in bokens metadata. Du kan använda pluggbrädor att ändra följande fält: författare, author_sort, språk, förläggare, taggar, titel, title_sort. Denna funktion hjälper människor som vill använda olika metadata i böcker på enheter för att lösa sortering- eller visningsproblem.

När du skapar en pluggbräda anger du format och enheten för vilken pluggbrädan ska användas. En speciell anordning tillhandahålls, save_to_disk, som används när du sparar format (i motsats till att skicka dem till en enhet). När du har valt formatet och enheten, väljer du de metadatafälten att ändra, ger mallar för att leverera de nya värdena. Dessa mallar är anslutna till sina destinationsfält, därav namnet pluggbräda. Du kan naturligtvis använda sammansatta kolumner i dessa mallar.

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.

Användbara tips

Du kan hitta följande tips användbart.

  • Skapa en anpassad sammansatt kolumn för att testa mallar. När du har kolumnen, kan du ändra dess mall genom att dubbelklicka på kolumnen. Dölj kolumnen när du inte testar.
  • Mallar kan använda andra mallar genom att referera en sammansatt anpassad kolumn.
  • 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.