Calibre şablon dili

The calibre template language is used in various places. It is used to control the folder structure and file name when saving files from the calibre library to the disk or e-book reader. It is also used to define “virtual” columns that contain data from other columns and so on.

Temel şablon dili çok basittir, ama çok güçlü gelişmiş özellikleri vardır. Ana fikir şablonun metinden oluşması ve isimlerin işlenen kitaptan gelen ilgili metadata ile değiştirilecek süslü parantez içinde olmasıdır. Yani örneğin, calibre’de kitapları aygıta kaydetmede kullanılan ön tanımlı şablon:

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

“Isaac Asimov”dan “The Foundation” kitabı için şu şekle gelir:

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

Yatık çizgiler metindir, belirdikleri yerde şablona koyulurlar. Örneğin, şablonunuz şu ise:

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

“Isaac Asimov”dan “The Foundation” kitabı için şu şekle gelir:

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

Calibre’de uygun tüm metadata alanlarını, kendiniz oluşturduğunuz özel sütunlar da dahil olmak üzere bir şablonda kullanabilirsiniz. Bir sütunun şablon adını bulmak için farenizi sütun başlığı üzerine getirin. Özel alanlar için isimler (kendi oluşturduğunuz sütunlar) ilk karakter olarak # alırlar. Seri biçimli özel alanlar için her zaman, bu seri için seri indisi olan #seriesname_index isimli ek bir alan vardır. Yani #myseries isimli bir özel seri alanınız varsa, #myseries_index isimli bir alan da olacaktır.

Sütun tabanlı alanlara ek olarak, şunu da kullanabilirsiniz:

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

Belirli bir kitabın belirli bir metadata parçası olmazsa, şablondaki alan otomatik olarak bu kitap için kaldırılır. Şu örneği düşünün:

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

Kitabın bir serisi varsa, şablon şunu üretir:

Asimov, Isaac/Foundation/Second Foundation 3

ve kitabın serisi yoksa:

Asimov, Isaac/Second Foundation

(calibre çift yan çizgileri veya satır sonu boşlukları otomatik olarak kaldırır).

Gelişmiş biçimleme

Şablonlarla basit yer değişikliklerinden fazlasını yapabilirsiniz. Duruma bağlı olarak metin ekleyebilir ve değiştirilen verinin nasıl biçimleneceğini kontrol edebilirsiniz.

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

Örneğin, şablonu kullanmak istediğinizi ele alalım:

{series} - {series_index} - {title}

Kitabın serisi yoksa, cevap - - title olacaktır. Çoğu insan sonucun tire işaretleri olmadan basitçe title olmasını terchi eder. Bunu yapmak için genişletilmiş söz dizimi kullanın {field:|prefix_text|suffix_text}. Bu söz dizimini kullandığınızda, alanın SERIES değeri varsa sonuç ``prefix_textSERIESsuffix_text``olacaktır. Alanın bir değeri yoksa, sonuç boş karakter dizisi olur (hiçbir şey); ön ek ve son ek göz ardı edilir. Ön ek ve son ek boşluk içerebilir. Ön ek ve son ek olarak alt şablonlar (`{ … }`) veya fonskiyonlar (aşağıya göz atın) kullanmayın.

Bu söz dizimini kullanarak yukardaki seri problemini şablonda şöyle çözebiliriz:

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

Tireler kitabın yalnızca bir seri indisi varsa içerilir, seri indisi de yalnızca seri varsa olacaktır.

Notlar: ön ek ya da son ek kullanmak istiyorsanız : karakterini eklemelisiniz. Ya | karakterlerini kullanmamalı ya da ikisini de kullanmalısınız; {field:| - }` de olduğu gibi birini kullanmaya izin verilmez. ``{series:|| - }``de olduğu gibi herhangi bir tarafa metin sağlanmayabilir. ``{title:||} kullanmak {title} kullanmak ile aynıdır.

İkincisi: biçimleme. series_index’in her zaman takip eden sıfırları olan üç rakam şeklinde biçimlenmesini istediğinizi farz edelim. Bu işimizi görürdü:

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

Takip eden sıfırlar yerine takip eden boşluklar için, şunu kullanın:

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

İzleyen sıfırlar için, şunu kullanın:

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

Alt değerleri olan (ör., 1.1) seri indisleri kullanırsanız, kesirli noktaların sıralanmasından emin olmak isteyebilirsiniz. Örneğin, düzgün sıralanması için 1 ve 2.5 indislerinin 01.00 ve 02.50 olarak görünmesini isteyebilirsiniz. Bunu yapmak için, şunu kullanın:

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

Verinin yalnızca ilk iki harfini istiyorsanız, şunu kullanın:

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

Gelişmiş özellikler

Özel sütunlarda şablon kullanmak

Bazı durumlarda calibre’nin normalde göstermediği metadata’yı göstermek isteyebilirsiniz, veyea veriyi calibre’nin normalde gösterdiğinden farklı biçimde göstermek isteyebilirsiniz. Örneğin, calibre’nin göstermediği ISBN’i göstermek isteyebilirsiniz. Bu iş için ‘diğer sütunlardan inşa edilen sütun’ (burdan sonra birleşik sütunlar olarak geçecektir) oluşturarak özel sütunlar kullanabilir, ve bir şablon girebilirsiniz. Sonuç: calibre bu şablonun değerlendirme sonuçlarını bir sütunda gösterir. ISBN göstermek için, sütun oluşturun ve şablon kutusuna {identifiers:select(isbn)} girin. Virgülle ayrılmış iki seri özel sütun göstermek için, {#series1:||,}{#series2} kullanın.

Birleşik sütunlar, biçimleme dahil tüm şablon seçeneklerini kullanabilirler.

Birleşik sütundaki veriyi değiştiremezsiniz. Bir birleşik sütunu herhangi bir öğeye çift tıklayarak düzenlerseniz, şablonu düzenleme için açarsınız, altındaki veriyi değil. GUI üzerinde şablon düzenleme birleşik sütunları değiştirme ve test etme için hızlı bir yöntemdir.

Şablonlarda fonksiyon kullanma - tekli-fonksiyon kipi

Normalde başlık harfleri boyutundayken, bir alanın değerini büyük harflerler göstermek istiyorsunuz diyelim. Bunu (ve daha bir çok şeyi) şablonlar için kullanılabilir fonksiyonlarla yapabilirsiniz. Örneğin, başlığı büyük harfle göstermek için {title:uppercase()} kullanın. Başlık boyutunda göstermek için {title:titlecase()} kullanın.

Fonksiyon referansları biçimleme kısmında : den sonra | veya kapatan } den önce belirir. Hem bir biçim hem fonksiyon referansınız varsa, fonksiyon ikinci bir : den sonra gelir. Fonksiyonlar her zaman () ile bitmelidir. Bazı fonksyionlar ek değerler (bağımsız değişken) alabilir, bunlar da () içine gider.

Fonksiyonlar her zaman biçim tanımlamalarından önce uygulanır. Bu sıranın hem biçim hem de bir fonksiyon ile gösterildiği bir örnek için aşağıya göz atın.

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

Önemli: Programlama deneyiminiz varsa, bu kipteki söz diziminin (tekli fonksiyon) beklediğiniz gibi olmayabileceğine dikkat edin. Karakter dizileri tırnak içinde değildir. Boşluklar belirgindir. Tüm bağımsız değişkenler sabit olmalıdır; alt-değerlendirme yoktur. Alt şablonları (`{ … }`) fonksiyon değişkeni olarak kullanmayın. Bunun yerine, şablon program kipi ve genel program kipi kullanın.

Bir çok fonksiyon düzenli ifadeler kullanır. Tüm durumlarda, düzenli ifade eşleşmeleri büyük küçük harf bağımsızdır.

Kullanılabilir fonksyionlar aşağıda listelenmiştir. Fonksiyonlar için tanımlayıcı belgelendirme Fonksiyon sınıflandırma kısmındadır:

  • lowercase() – alanın değerini küçük harfle döndür.

  • uppercase() – alanın değerini büyük harfle döndür.

  • titlecase() – alanın değerini başlık boyutunda döndür.

  • capitalize() – değeri ilk harfi büyük diğerleri küçük olacak şekilde döndür.

  • contains(örüntü, eşleşirse metin, eşleşmezse metin) – alanın örüntü düzenli ifadesi ile eşleşme içerip içermediğini kontrol eder. Eşleşme olursa eşleşirse metin aksi durumda eşleşmezse metin döndürür.

  • count(separator) – değeri separator ile ayrılmış bir öğe listesi olarak yorumlar, listedeki öğe sayısını döndürür. Çoğu liste ayraç olarak virgül kullanır, ama yazarlar ampersan işareti kullanır. Örnekler: {tags:count(,)}, {authors:count(&)}

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

  • human_readable() – değerin bir sayı olmasını bekler ve bu sayıyı KB, MB, GB vs. biçiminde temsil eden bir karakter dizisi döndürür

  • ifempty(text) – alan boş değilse, alanın değerini döndürür. Aksi halde text döndürür.

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

  • language_codes(lang_strings)lang_strings ile geçirilen karakter dizileri için dil kodlarını döndür. Karakter dizileri mevcut yerelle aynı dilde olmalıdır. Lang_strings virgülle ayrılmış bir listedir.

  • language_strings(lang_codes, localize)lang_codes ile geçirilen dil kodları için karakter dizilerini getirir. localize sıfır ise, karakter dizisini İngilizce olarak döndürür. localize sıfır değilse, karakter dizilerini mevcut yerel dilinde döndürür. Lang_codes virgülle ayrılmış listedir.

  • list_item(index, separator) – alanı separator ile ayrılmış öğe listesi olarak yorumla, index`inci elemanı döndür. İlk öğe sıfır rakamıdır. Son öğe `list_item(-1,separator) kullanarak döndürülebilir. Öğe listede değilse, boş değer döndürülür. Ayraç count fonksiyonundakiyle aynı anlamı taşır.

  • lookup(pattern, field, pattern, field, ..., else_field) – switch gibidir, farkı bağımsız değişkenlerin metin değil, alan (metadata) ismi olmasıdır. Uygun alanın değeri çekilecek ve kullanılacaktır. Bileşik sütunlar alanlar olduklarından, bu fonksiyonu bir bileşik alanda kullanarak başka bir bileşik alanın değerini kullanabilirsiniz. Değişken kayıt yolları inşa ederken oldukç faydalıdır (bu konuya sonra değinilecek).

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

  • select(key) – alanı, öğeler “id:value” biçiminde olmak üzere, virgülle ayrılmış öğe listesi olarak yorumlar. id’nin anahtara eşit olduğu çifti bul, ve ilgili değeri döndür. Bu fonksiyon bir kitap için tanımlayıcılardan isbn gibi bir değeri çıkarmak için özellikle faydalıdır.

  • shorten(left chars, middle text, right chars) – Alanın kısaltılmış bir sürümünü döndürür, bu sürüm alanın solundan sol karakterler, ardından orta karakterler, ve alanın sağından sağ karakterler`den oluşur. `Sol karakterler ve sağ karakterler tam sayı olmalıdır. Örneğin, kitabın başlığının Ancient English Laws in the Times of Ivanhoe olduğunu varsayalım, ve bunu en fazla 15 karakterlik bir boşluğa sığdırmaya çalıştığınızı. {title:shorten(9,-,5)} kullanırsanız, sonuç Ancient E-nhoe olacaktır. Alanın uzunluğu sol karakterler + sağ karakterler + middle text uzunluğundan kısa olursa, alan olduğu gibi kullanılır. Örneğin, The Dome başlığı değiştirilmez.

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

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

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

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

  • switch(pattern, value, pattern, value, ..., else_value) – her pattern, value çifti için, alanın pattern düzenli ifadesiyle eşleşip eşleşmediğini kontrol eder, ve eşleşiyorsa, bu value değerini döndürür. pattern eşleşmiyorsa, else_value döndürülür. İstediğiniz kadar pattern, value çiftiniz olabilir.

  • test(text if not empty, text if empty) – alan boş değilse text if not empty, boşsa text if empty döndürür.

  • transliterate() – Latin alfabesinden kaynak alandaki kelimelerin seslerine yakın biçimlenmiş karakter dizisi döndürür. Örneğin, kaynak alan Фёдор Миха́йлович Достоевский ise fonksiyon Fiodor Mikhailovich Dostoievskii döndürür.’

Şimdi, fonksiyon ve biçimlendirmeleri aynı alanda yapmaya ne dersiniz. 003``de olduğu gibi önünde sıfırlar olan ``#myint adında özel bir tam sayı sütununuz olduğunu farz edin. Bunu yapmak için 0>3s şeklinde bir biçim kullanırsınız. Ancak ön tanımlı olarak bir sayı (tam veya kesirli) sıfıra eşitse alan boş değeri üretir, yani sıfır değerler 000 yerine hiçbir şey üretmez. Gerçekten 000 değerleri görmek istiyorsanız, hem biçim karakter dizisini hem de ifempty fonksiyonunu kullanıp boş değeri sıfıra çevirin. Alan referansı şu şekilde olurdu:

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

Ön ve son ek kullanabileceğinizi de not edin. Sayının [003] veya [000] şeklinde görünmesini istiyorsanız, alanı kullanın:

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

Şablonlarda fonksiyon kullanma - şablom program kipi

Şablon dil program kipi tekli-fonksiyon kipinden farklı olarak diğer metadata alanlarına referans yapan, değerleri değiştiren, aritmetik işlem yapan şablon ifadeleri yazmanıza izin verir. Makul tamamlıkta bir programlama dilidir.

Yukarıda belgelenen fonksiyonları şablon program kipinde kullanabilirsiniz. Detaylar için aşağıya göz atın.

Bir örnekle başlayalım, şablonunuzun bir kitabın varsa serilerini, yoksa özel bir alan olan #genre yi göstermesini istediğinizi ele alalım. Temel dille bunu yapamazsınız çünkü bir şablon ifadesinde başka metadata alanına referans veremezsiniz. Program kipinde, yapabilirsiniz. Aşağıdaki ifade çalışır:

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

Örnek bir çok şey gösteriyor:

  • ifade :' ile başlıyor ve ' ile bitiyorsa program kipi kullanılır. Diğer her şey tekli-fonksiyon olarak ele alınır.
  • $ değişkeni ifadenin üzerinde işlem yaptığı alan yerine geçer, bu durumda #series.
  • fonksiyonlara tüm bağımsız değişkenleri verilmelidir. Varsayılan bir değer yoktur. Örneğin, standart yerleşik fonksiyonlara kaynak alanını gösteren ek bir ilk parametre verilmelidir, bu tekli-fonksiyon kipinden belirgin bir değişikliktir.
  • boşluk karakterleri göz ardı edilir ve ifadenin herhangi bir yerinde kullanılabilir.
  • sabit karakter dizileri eşleşen tırnak işaretleri arasındadır, ' veyea ".

Dil nerdeyse tamamen fonksiyonlardan oluştuğundan fonksiyonel dillere benzer. Her ifade bir fonksiyondur. Her deyim bir fonksiyondur. Sabitler ve tanımlayıcılar sabitlerce gösterilen veya tanımlayıcılarda saklanan değerleri döndüren fonksiyonlar olarak düşünülebilir.

Dilin söz dizimi aşağıdaki dil bilgisi ile gösterilmiştir:

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

Yorumlar satır başında ‘#’ karakteri olan sastırlardır.

Bir ``expression``ın her zaman değeri vardır, ya sabitin değeri, ya tanımlayıcıda içerilen değer, ya da bir fonksiyon tarafından döndürülen değer. Bir ``statement``ın değeri ifade dizisindeki son deyimin değeridir. Yani programın değeri (ifade):

1; 2; 'foobar'; 3

3 olur.

Karmaşık ama pek anlamlı olmayan bir program örneği daha iyi anlatacaktır:

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

Bu program aşağıdakileri yapar:

  • bakılan alanın seris_index olduğunu belirtir. Bu, $ değişkeninin değerini ayarlar.
  • 3 parametre (str, start, end) alan substr fonksiyonunu çağırır. Karakter dizisinden start ile end arasında karakterleri çıkararak oluşturulan karakter dizisini, sıfır-tabanlı ( ilk karakter sıfır karakteridir) döndürür. Bu durumda karakter dizisi strcat fonksiyonu ile hesaplanır, start 0, end 6 dır. Bu durumda substr dönmeden önce değerlendirilmesi gereken, strcat tarafından döndürülen karakter dizisinin ilk 6 karakterini döndürür.
  • calls the strcat (string concatenation) function. Strcat accepts 1 or more arguments, and returns a string formed by concatenating all the values. In this case there are three arguments. The first parameter is the value in $, which here is the value of series_index. The second paremeter is the constant string '->'. The third parameter is the value returned by the cmp function, which must be fully evaluated before strcat can return.
  • cmp fonksiyonu 5 değişken alır (x, y, lt, eq, gt). x ve y değişkenlerini karşılaştırır ve x< y ise üçüncü değişken olan lt, x == y ise dördüncü değişken eq, x > y ise beşinci değişken gt yi döndürür. Tüm fonksiyonlarda olduğu gibi, tüm parametreler ifade olabilirler. Bu durumda ilk parametre (x için değer) series_index’in 2’ye bölümünün sonucudur. İkinci parametre y sabit 1``dir. Üçüncü parametre ``lt bir ifadedir (daha sonra anlatılacak). Dördüncü parametre eq sabit karakter dizisi ``’eq’``dir. Beşinci parametre sabit karakter dizisi ``’gt’``dir.
  • Üçüncü parametre (lt için olan) bir ifadedir, veya deyimler dizisidir. Bir ifadenin aynı zamanda deyim olduğunu unutmayın (noktalı virgül ile ayrılmış bir dizi deyim), listedeki son deyimin değerini döndürür. Bu durumda, program önce 1 değerini yerel değişken c``ye atar, ardından sondan c'inci karakterin çıkarılmasıyla elde edilen alt karakter dizisi döndürür. c her zaman sabit değer ``1 içereceğinden, alt karakter dizisi ikinciden sonuncuya olan karakterleri döndürür, veya 't123'.
  • Üçüncü parametreye değeri sağlayan ifade çalıştığında, cmp bir değer döndürebilir. Bu noktada, ``strcat` bir değer döndürebilir, sonra ``substr` bir değer döndürebilir. Program ardından sonlanır.

series_index’in çeşitli değerleri için, program döner:

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

Tekli-fonksiyon kipi altında listelenen tüm fonksiyonlar program kipinde kullanılabilir. Böyle yapmak için, yukarıda belgelenen parametrelere ek olarak, fonksiyonun üzerinde işlem yapacağı değeri sağlamalısınız. Örneğin, program kipinde test fonksiyonunun parametreleri şunlardır test(x, text_if_not_empty, text_if_empty). Test edilecek değer olan x parametresi, hemen her zaman bir değişken ya da fonksiyon çağrısı, genellikle field() olacaktır.

Aşağıdaki fonksiyonlar tekli-fonksiyon kipinde açıklananlara ek olarak kullanılabilirler. Yukarıdaki örnekten, tekli-fonksiyon kipi fonksiyonlarının üzerinde işlem yapılacak ek bir ilk değer parametre alanına ihtiyaç duyduğunu unutmayın. Atamanın id parametresi hariç, tüm parametreler ifade olabilirler (bir dizi deyim). Fonksiyonlar için tam belgelendirmenin Fonksiyon sınıflandırma kısmında olduğunu unutmayın.

  • and(value, value, ...) – tüm değerler boş değilse “1” karakter dizisi döndürür, aksi halde boş karakter dizisi döndürür. Bu fonksiyon test veya first_non_empty ile iyi çalışır. İstediğiniz kadar değeriniz olabilir.

  • add(x, y) – x + y döndürür. x veya y sayı değilse bir istisna fırlatır.

  • assign(id, val) – id’ye val atar, ardından val döndürür. id bir tanımlayıcı olmalıdır, deyim değil

  • approximate_formats() – bir noktada kitapla ilişkilenmiş biçimlerin virgülle ayrılmış listesini döndürür. Listenin düzgün olması garanti değildir, her ne kadar muhtemelen düzgün olacak olsa da. Bu fonksiyon şablon program kipinde {:'approximate_formats()'} kullanarak çağrılabilir. Biçim isimlerinin büyük harfle yazıldığını unutmayın, EPUB gibi.

  • author_links(val_separator, pair_separator) – yazar listesi ve yazarın bağlantı değerini author1 val_separator author1link pair_separator author2 val_separator author2link vs. şeklinde döndürür. Yazar bağlantısından val_separator karakter dizisi ile ek boşluk olmadan ayrılır. author:linkvalue çiftleri pair_separator karakter dizisi değişkeni ile ek boşluk olmadan ayrılır. Yazar adları ya da bağlantılarında geçmeyen ayraç karakter dizilerini seçmek size kalmıştır. Yazar bağlantısı boş olsa da yazar eklenir.

  • author_sorts(val_separator) – Kitabın yazarları için yazar sıralama değerleri listesi içeren bir karakter dizisi döndürür. Sıralama yazar metadata’sında olandır (kitaplardaki author_sort’dan farklıdır). Döndürülen liste yazar sıralama 1 val_separator yazar sıralama 2 vs. şeklindedir. Bu listedeki yazar sıralama değerleri kitaptaki yazarlarla aynı sıradadır. val_separator etrafında boşluklar istiyorsanız ayraç karakter dizisinde ekleyin

  • booksize() – calibre ‘size’ alanının değerini döndürür. Herhangi biçim yoksa ‘’ döndürür.

  • cmp(x, y, lt, eq, gt) – x ve ye yi ikisini de sayıya çevirdikten sonra karşılaştırır. x < y ise lt döndürür. x == y ise eq döndürür. Aksi halde gt döndürür.

  • 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)date1 ile date2 arasındaki gün sayısını döndürür. date1 date2 den büyükse sayı pozitiftir, değilse negatiftir. date1 veya date2 tarih değillerse, fonksiyon boş karakter dizisi döndürür.

  • divide(x, y) – x / y döndürür. x veya y sayı değilse istisna fırlatır.

  • eval(string) – karakter dizisini bir program olarak değerlendirir, yerel değişkenleri geçirir (atananları). Bu, şablon işlemcisinin yerel değişkenlerden karmaşık sonuçlar oluşturmasına olanak verir. { ve } karakterleri özel olduklarından, { karakteri için [[ ve ‘}’ karakteri için ]] kullanmalısınız; otomatik olarak dönüştürüleceklerdir. Ayrıca ön ek ve son eklerin (|prefix|suffix söz dizimi) şablon program kipi kullanılırken bu fonksiyona değişken olarak kullanılamayacağını unutmayın.

  • field(name)name ile isimlendirilen metadata alanını döndürür.

  • first_matching_cmp(val, cmp1, result1, cmp2, r2, ..., else_result) – compares val < cmpN in sequence, returning resultN for the first comparison that succeeds. Returns else_result if no comparison succeeds. Example:

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

    returns “large”. The same example with a first value of 16 returns “giant”.

  • first_non_empty(value, value, ...) – returns the first value that is not empty. If all values are empty, then the empty value is returned. You can have as many values as you want.

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

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

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

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

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

    Başka bir örnek: {series:re(([^\s])[^\s]+(\s|$),\1)}{series_index:0>2s| - | - }{title} şablonu için şunu kullanın:

    program:
        strcat(
            re(field('series'), '([^\s])[^\s]+(\s|$)', '\1'),
            finish_formatting(field('series_index'), '0>2s', ' - ', ' - '),
            field('title')
        )
    
  • formats_modtimes(format_string) – return a comma-separated list of colon-separated items representing modification times for the formats of a book. The format_string parameter specifies how the date is to be formatted. See the format_date() function for details. You can use the select function to get the mod time for a specific format. Note that format names are always uppercase, as in EPUB.

  • formats_paths() – return a comma-separated list of colon-separated items representing full path to the formats of a book. You can use the select function to get the path for a specific format. Note that format names are always uppercase, as in EPUB.

  • formats_sizes() – return a comma-separated list of colon-separated items representing sizes in bytes of the formats of a book. You can use the select function to get the size for a specific format. Note that format names are always uppercase, as in EPUB.

  • has_cover() – kitabın bir kapağı varsa Yes, aksi durumda boş karakter dizisi döndürür

  • not(value) – returns the string “1” if the value is empty, otherwise returns the empty string. This function works well with test or first_non_empty.

  • list_difference(list1, list2, separator) – return a list made by removing from list1 any item found in list2, using a case-insensitive comparison. The items in list1 and list2 are separated by separator, as are the items in the returned list.

  • list_equals(list1, sep1, list2, sep2, yes_val, no_val) – return yes_val if list1 and list2 contain the same items, otherwise return no_val. The items are determined by splitting each list using the appropriate separator character (sep1 or sep2). The order of items in the lists is not relevant. The comparison is case-insensitive.

  • list_intersection(list1, list2, separator) – return a list made by removing from list1 any item not found in list2, using a case-insensitive comparison. The items in list1 and list2 are separated by separator, as are the items in the returned list.

  • list_re(src_list, separator, include_re, opt_replace) – Önce separator karakterini kullanarak src_list`i öğelere ayırarak bir liste oluştur. Listedeki her öğenin `include_re ile eşleşip eşleşmediğini kontrol et. Eşleşirse, döndürülecek listeye ekle. opt_replace boş karakter dizisi değilse, öğeyi döndürülen listeye eklemeden önce yer değiştirmeyi uygula.

  • list_re_group(src_list, separator, include_re, search_re, template_for_group_1, for_group_2, ...) – list_re except gibi yer değiştirmeler seçime bağlı değildir. Yer değiştirmeleri kullanırken re_group(item, search_re, template …) kullanır.

  • list_sort(list, direction, separator) – büyük küçük harf bağımsız sıralanmış liste döndür. direction sıfır ise, liste artan şekilde sıralanır, aksi halde azalan şekilde. Liste öğeleri döndürülen liste gibi separator ile ayrılmıştır.

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

  • multiply(x, y) – x * y döndürür. x veya y sayı değilse bir istisna fırlatır.

  • ondevice() – ondevice ayarlanmışsa “Yes” karakter dizisini, aksi halde boş karakter dizisi döndürür

  • or(value, value, ...) – herhangi bir değer boş değilse “1” karakter dizisini, aksi halde boş karakter dizisi döndürür. Bu fonksiyon test veya first_non_empty ile iyi çalışır. İstediğiniz kadar değeriniz olabilir.

  • print(a, b, ...) – bağımsız değişkenleri standart çıktıya yazdırır. Calibre’yi komut satırından başlatmadığınız takdirde (calibre-debug -g) çıktı bir kara deliğe gideceketir.

  • raw_field(name) – Herhangi biçimlendirme uygulamadan name ile isimlendirilmiş metadata alanını döndürür.

  • raw_list(name, separator) – Herhangi biçimlendirme veya sıralama uygulamadan ve separator ile ayrılmış öğelerle, name ile isimlendirilmiş metadata listesini döndürür.

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

    {series:'re_group($, "(\S* )(.*)", "[[$:uppercase()]]", "[[$]]")'}
    
  • series_sort() – seri sıralama değerini döndürür.

  • strcat(a, b, ...) – istenilen sayıda değişken alabilir. Tüm değişkenlerin uç uca eklenmesiyle oluşturulmuş bir karakter dizisi döndürür.

  • strcat_max(max, string1, prefix2, string2, ...) – Bağımsız değişkenlerin uç uca eklenmesiyle oluşturulmuş bir karakter dizisi döndürür. Döndürülen değer string1 olarak ilklendirilir. Prefix, string çiftleri elde edilen karakter dizisinin boyu max`dan küçük olduğu sürece değerin sonuna eklenir. String1 max’dan büyük olsa da string1 döndürülür. İstediğiniz kadar `prefix, string çifti geçirebilirsiniz.

  • strcmp(x, y, lt, eq, gt) – x ve y karakter dizileri üzerinde büyük küçük harf bağımsız karşılaştırma gerçekleştirir. x < y ise lt döndürür. x == y ise eq döndürür. Aksi halde gt döndürür.

  • strlen(a) – Değişken olarak geçirilen karakter dizisinin uzunluğunu döndürür.

  • substr(str, start, end)str``nin ``start``dan ``end``e kadar olan karakterlerini döndürür. ``str``nin ilk karakteri sıfırıncı karakterdir. end negatif ise, sağdan sayıldığında kaç karakter olduğunu ifade eder. end sıfır ise, son karakteri ifade eder. Örneğin, ``substr('12345', 1, 0) '2345' döndürür, ve substr('12345', 1, -1) '234' döndürür.

  • subtract(x, y) – x - y döndürür. x veya y sayı değilse bir istisna fırlatır.

  • today() – bugün için bir karakter dizisi döndürür. Bu değer format_date veyea days_between ile kullanılması için tasarlanmıştır, ama her karakter dizisi gibi değiştirilebilir. Tarih ISO biçimindedir.

  • template(x) – x’i bir şablon olarak değerlendirir. Değerlendirme kendi bağlamında yapılır, anlamı değerlerin çağıran ve şablon değerlendirmesi arasında paylaştırılmıyor olduğudur. { ve } özel karakterler olduklarından { yerine [[ ve ‘}’ yerine ]] kullanmalısınız; otomatik olarak dönüştürülürler. Örneğin template('[[title_sort]]') ``{title_sort} şablonunu değerlendirecek ve değerini döndürecektir. Ayrıca ön ek ve son eklerin (|prefix|suffix söz dizimi) şablon program kipi kullanılarak bu fonksiyona bağımsız değişken olarak verilemeyeceğini not edin.

Fonksiyon sınıflandırma

Genel program kipi kullanma

Daha karmaşık şablon programları için, bazen şablon söz diziminden (tüm { ve } karakterleri) kaçınmak ve daha klasik görünümlü bir program yazmak daha kolaydır. Bunu calibre’de şablona program: ile başlayarak yapabilirsiniz. Bu durumda, hiçbir şablon işleme yapılmaz. Özel değişken $ ayarlanmaz. Doğru sonucu üretmek programınıza kalmıştır.

program: kipinin bir avantajı, parantezlerin artık özel olmamasıdır. Örneğin template() fonksiyonunu kullanırken [[ ve ]] kullanmak zorunlu değildir. Başka bir avantaj, program kipi şablonların Python’a derlenmesi ve diğer iki kipteki şablonlardan oldukça hızlı çalışmasıdır. Hızdaki artış şablonlardaki karmaşıklığa bağlıdır; şablon ne kadar karmaşıklaşırsa gelişme de o kadar fazla olur. Derleme compile_gpm_templates (Genel Program Kipi şablonlarını Python’a Derle) ile açılıp kapatılabilir. Derlemenin kapatılmasının ana sebebi derlenen şablonun çalışmıyor olması durumu olabilir, bu durumda lütfen bir hata raporlayın.

Takip eden örnek MobileRead forumunun bir program: kipi uygulaması reçetesi: “Serileri ilk harflerini veya kısaltılmış hallerini kullanarak başlığa koy. Sonundaki makaleleri seri adından (varsa) çıkar.” Örneğin, Lord of the Rings serisindeki The Two Towers kitabı için, reçete LotR [02] The Two Towers verir. Standart şablonlar kullanarak, aşağıda açıklandığı gibi, reçete üç özel sütun ve bir santrala ihtiyaç duyar:

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

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

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

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

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

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

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

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

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

Aşağıdaki program özel başlık değerini hesaplayan bir programın sonuçlarını tutan sadece bir özel sütun kullanarak asıl reçeteyle aynı sonuçları üretir:

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

Programı santralin şablon kutusuna koyarak yukardaki özel sütunlar kullanmadan yapmak da mümkün olurdu. Ancak böyle yapmak için, santral metni birden çok satır düzenlemeye izin vermediğinden tüm yorum satırlarının kaldırılması gerekirdi. Özel sütuna sahip olmamanın programın koca tek bir satır olarak getirdiği zorluk artışına deyip deymeyeceği tartışılır.

User-defined template functions

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

Kayıt et/gönder şablonları ile ilgili özel notlar

Bir şablon diske kaydet veya aygıta gönder şablonu ile kullanıldığında özel işlemler uygulanır. Alanların değerleri temizlenir, dosya sistemine özel karakterler alt çizgiler ile değiştirilir, yatık çizgiler dahil. Bunun anlamı alan metni kullanılarak klasör oluşturulamayacağıdır. Ancak yatık çizgiler ön ek veya son ek karakter dizilerinden değiştirilmezler, yani bu karakter dizilerindeki yatık çizgiler klasörlerin oluşturulmasına sebep olur. Bu sebepten, değişken derinlikli klasör yapıları oluşturabilirsiniz.

Örneğin, series/series_index - title dizin yapısını istediğimizi varsayın, series’in olmama durumunda, başlık en üst klasörde olmalıdır. Bunu yapan şablon şu şekildedir:

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

Yatık çizgi ve tire sadece seriler boş değilken görülür.

Arama fonksiyonu daha da ince işlemler yapmamıza olanak verir. Örneğin, bir kitabın serisi varsa, series/series index - title.fmt şeklinde bir dizin yapısı istediğimizi varsayalım. Kitabın serisi yoksa da genre/author_sort/title.fmt. Kitabın türü de yoksa, ‘Unknown’ kullanmak istiyoruz. Serinin değerine bağlı olarak, iki tane tamamen değişik yol istiyoruz.

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

Templates and plugboards

Santraller kitaba yazılan metadata’yı diske kaydetme ve aygıta gönderme işlemlerinde değiştirmeye yarar. Bir santral size kitabın metadata’sına yazılacak veriyi sağlayan şablonu belirtme izni verir. Santraller kullanarak şu alanları değiştirebilirsiniz: authors, author_sort, language, publisher, tags, title, title_sort. Bu özellik sıralama ya da görüntüleme sorunlarını aygıttaki kitapta değişik metadata kullanarak çözmek isteyen insanlara yardımcı olur.

Bir santral oluşturduğunuzda, santralin kullanılacağı biçim ve aygıtı belirtirsiniz. Biçimleri (bir aygıta göndermenin aksine) kaydederken kullanılan, save_to_disk adında özel bir aygıt sağlanır. Biçim ve aygıtı seçtiğinizde yeni değerleri sağlayacak şablonları sağlar ve değiştirilecek metadata alanlarını seçersiniz. Bu şablonlar hedef alanlarına bağlıdırlar, santral adı da burdan gelir. Tabi ki bu şablonlarda bileşik sütunlar kullanabilirsiniz.

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

  • biçim ve aygıtla birebir eşleşen bir santral, örn., EPUB ve ANDROID
  • biçim ve özel any device seçimi ile birebir eşleşen bir santral, örn., EPUB ve any device
  • özel any format seçimi ve aygıtla birebir eşleşmeli bir santral, örn., any format ve ANDROID
  • any format ve any device olan bir santral

Etiket ve yazar alanları özel işlem gerektirir, çünkü her iki alan da birden fazla öğe tutabilir. Bir kitabın birden çok etiketi ve yazarı olabilir. Bu iki alandan birinin değişeceğini belirttiğinizde, şablonun sonucu birden fazla öğenin orada olup olmadığı hususunda incelenir. Etiketler için, sonuç, calibre’nin virgül bulduğu yerlerden kesilerek ayrılır. Örneğin, şablon Thriller, Horror değerini üretiyorsa, sonuç iki etiket olur Thriller ve Horror. Etiketin ortasına virgül koymanın bir yolu yoktur.

Aynı şey yazarlar için de geçerlidir, ama ayırma için virgül yerine & (ampersand) karakteri kullanılır. Örneğin, şablon Blogs, Joe&Posts, Susan değerini üretiyorsa, kitap iki yazarı var olarak sonlanacaktır, Blogs, Joe ve Posts, Susan. Şablon Blogs, Joe;Posts, Susan üretiyorsa, kitabın biraz garip isimli tek bir yazarı olacaktır.

Santraller diske kaydedilirken ya da aygıta yazılırken kitaba yazılan metadata’yı etkilerler. Santraller diske kaydet ve aygıta gönder tarafından dosya isimlerini oluşturmakta kullanılan metadata’yı etkilemezler. Bunun yerine, dosya isimleri, uygun seçenekler penceresinde girilen şablonlar kullanılarak oluştururlur.

Helpful tips

Şu ipuçlarını faydalı bulabilirsiniz.

  • Şablonları test etmek için özel bir bileşik sütun oluşturun. Sütunu oluşturduğunuzda, sütuna çift tıklayarak şablonunu değiştirebilirsiniz. Test etmediğinizde sütunu gizleyin.
  • Şablonlar bir bileşik özel sütuna referans vererek diğer şablonları kullanabilirler.
  • Bir santralde, özel şablon {} kullanarak bir alanı boş olarak ayarlayabilirsiniz (ya da boşla eş değer neyse). Bu şablon her zaman boş karakter dizisi olarak değerlenecektir.
  • Yukarıda sıfır değeri olsa bile sayıları göstermeye yarayan teknik standart alan series_index ile de çalışır.