A linguagem de modelos do Calibre

A linguagem de modelos do Calibre é utilizada em vários locais. É utilizada para controlar a estrutura de pastas e o nome de ficheiros quando guardar ficheiros da biblioteca Calibre no disco ou no leitor de ebooks. Também é utilizada para definir as colunas «virtuais» que contêm dados de outras colunas, e assim por diante.

The basic template language is very simple, but has very powerful advanced features. The basic idea is that a template consists of text and names in curly brackets that are then replaced by the corresponding metadata from the book being processed. So, for example, the default template used for saving books to device in calibre is:

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

No caso do livro «The Foundation» por «Isaac Asimov» ficará como:

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

The slashes are text, which is put into the template where it appears. For example, if your template is:

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

No caso do livro «The Foundation» por «Isaac Asimov» ficará como:

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

You can use all the various metadata fields available in calibre in a template, including any custom columns you have created yourself. To find out the template name for a column simply hover your mouse over the column header. Names for custom fields (columns you have created yourself) always have a # as the first character. For series type custom fields, there is always an additional field named #seriesname_index that becomes 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.

Para além dos campos baseados em colunas, também pode usar:

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

If a particular book does not have a particular piece of metadata, the field in the template is automatically removed for that book. Consider, for example:

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

Se um livro tiver uma série, o modelo produzirá:

Asimov, Isaac/Foundation/Second Foundation 3

e se um livro não tiver uma série:

Asimov, Isaac/Second Foundation

(o Calibre remove automaticamente barras múltiplas e espaços à esquerda ou à direita).

Formatação avançada

You can do more than just simple substitution with the templates. You can also conditionally include text and control how the substituted data is formatted.

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.

Por exemplo, se pretender usar este modelo:

{series} - {series_index} - {title}

If the book has no series, the answer will be - - title. Many 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.

Usando esta sintaxe, podemos resolver o problema das séries com este modelo:

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

Os hífenes serão incluídos apenas se o livro tiver um número da série, o que só ocorre quando possuir indicação de série.

Notes: you must include the : character if you want to use a prefix or a suffix. You must either use no | characters or both of them; using one, as in {field:| - }, is not allowed. It is OK not to provide any text for one side or the other, such as in {series:|| - }. Using {title:||} is the same as using {title}.

Segundo: formatação. Suponha que deseje garantir que o series_index seja sempre formatado com três dígitos e com zeros à esquerda. Isto seria o necessário:

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

Se em vez de zeros à esquerda pretende espaços à esquerda, use:

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

Para zeros à esquerda, use:

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

If you use series indices with sub values (e.g., 1.1), you might want to ensure that the decimal points line up. For example, you might want the indices 1 and 2.5 to appear as 01.00 and 02.50 so that they will sort correctly. To do this, use:

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

Se pretende apenas as duas primeiras letras da data, use:

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

Funcionalidades avançadas

Usar modelos em colunas personalizadas

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

Colunas compostas podem usar qualquer opção de modelo, incluindo formatação.

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

Using functions in templates - single-function mode

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

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

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

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

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

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

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

  • lowercase() – devolve o valor do campo em minúsculas.

  • uppercase() – devolve o valor do campo em maiúsculas.

  • titlecase() – devolve o valor do campo com maiusculização de título

  • capitalize()`devolve o valor com a primeira letra em maiúsculas e as restantes em minúsculas.

  • contains(pattern, text if match, text if not match) – checks if field contains matches for the regular expression pattern. Returns text if match if matches are found, otherwise it returns text if no match.

  • count(separator) – interpreta o valor como uma lista de itens separados por separator, retornando o número de itens na lista. A maioria das listas usam uma vírgula como separador, mas autores usam um E comercial. Exemplos: {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() – expects the value to be a number and returns a string representing that number in KB, MB, GB, etc.

  • ifempty(text) – if the field is not empty, return the value of the field. Otherwise return text.

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

  • language_codes(lang_strings) – return the language codes for the strings passed in lang_strings. The strings must be in the language of the current locale. Lang_strings is a comma-separated list.

  • language_strings(lang_codes, localize) – return the strings for the language codes passed in lang_codes. If localize is zero, return the strings in English. If localize is not zero, return the strings in the language of the current locale. Lang_codes is a comma-separated list.

  • list_item(index, separator) – interpreta o campo como uma lista de itens separados por separator, devolvendo o item index. O primeiro item é o número zero. O último item pode ser obtido usando list_item(-1,separator). Se o item não estiver na lista, então é devolvido o valor vazio. O separador tem o mesmo significado que na função de count .

  • lookup(pattern, field, pattern, field, ..., else_field) – like switch, except the arguments are field (metadata) names, not text. The value of the appropriate field will be fetched and used. Note that because composite columns are fields, you can use this function in one composite field to use the value of some other composite field. This is extremely useful when constructing variable save paths (more later).

  • rating_to_stars(use_half_stars) – Devolve a classificação como sequência de caracteres de estrelas. O valor deve ser um número entre 0 e 5. Defina use_half_stars como 1 se desejar caracteres de meia estrela para colunas de classificações personalizadas que sejam não inteiras, por exemplo 2.5.

  • 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) – interpreta o campo como uma lista de itens separados por vírgulas, com os itens na forma «id:value». Encontra o emparelhamento do id igual a key, e devolve o valor correspondente. Esta função é particularmente útil para extrair um valor, como um ISBN, de um conjunto de identificadores de um livro

  • shorten(left chars, middle text, right chars) – Devolve uma versão abreviada do campo, que consiste em caracteres left chars do início do campo, seguido por middle text, seguido pelos caracteres right chars do fim da string. Left chars e right chars devem ser inteiros. Por exemplo, suponha que o título do livro é Antigas Leis Inglesas nos Tempos de Ivanhoe, e quer que ele se ajuste a uma dimensão de, no máximo, 15 caracteres. Se usar {title:shorten(9,-,5)}, o resultado será Antigas I-nhoe. Se o comprimento do campo for menor que os caracteres à esquerda + caracteres à direita + o comprimento do texto do meio, então o campo será usado sem alterações. Por exemplo, o título A Cúpula não seria alterado.

  • 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_articles(separator) – returns the val with articles moved to the end. The value can be a list, in which case each member of the list is processed. If the value is a list then you must provide the list value separator. If no separator is provided then the value is treated as being a single value, not a list.

  • 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) – for each pattern, value pair, checks if the field matches the regular expression pattern and if so, returns that value. If no pattern matches, then else_value is returned. You can have as many pattern, value pairs as you want.

  • test(text if not empty, text if empty) – return text if not empty if the field is not empty, otherwise return text if empty.

  • transliterate() – Returns a string in a latin alphabet formed by approximating the sound of the words in the source field. For example, if the source field is Фёдор Миха́йлович Достоевский the function returns 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)}

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

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

Using functions in templates - template program mode

The template language program mode differs from single-function mode in that it permits you to write template expressions that refer to other metadata fields, 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 that 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 language because you cannot make reference to another metadata field within a template expression. In program mode, you can. The following expression works:

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

O exemplo mostra várias coisas:

  • program mode is used if the expression begins with :' and ends with '. Anything else is assumed to be single-function.

  • the variable $ stands for the field the expression is operating upon, #series in this case.

  • functions must be given all their arguments. There is no default value. For example, the standard built-in functions must be given an additional initial parameter indicating the source field, which is a significant difference from single-function mode.

  • white space is ignored and can be used anywhere within the expression.

  • constant strings are enclosed in matching quotes, either ' or ".

The language is similar to functional languages in that it is built almost entirely from functions. An expression is generally a function. Constants and identifiers can be thought of as functions returning the value indicated by the constant or stored in the identifier.

The syntax of the language is shown by the following grammar. For a discussion of “compare” and “if_expression” 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 ['else' statement] 'fi'
assignment      ::= identifier '=' expression
constant        ::= " string " | ' string ' | number
identifier      ::= sequence of letters or ``_`` characters

Linhas comentadas são linhas com um cardinal “#” no início da linha.

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

é 3.

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

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

Este programa faz o seguinte:

  • specify that the field being looked at is series_index. This sets the value of the variable $.

  • calls the substr function, which takes 3 parameters (str, start, end). It returns a string formed by extracting the start through end characters from string, zero-based (the first character is character zero). In this case the string will be computed by the strcat function, the start is 0, and the end is 6. In this case it will return the first 6 characters of the string returned by strcat, which must be evaluated before substr can return.

  • calls the strcat (string concatenation) function. Strcat accepts 1 or more arguments, and returns a string formed by concatenating all the values. In this case there are three arguments. The first parameter is the value in $, which here is the value of series_index. The second paremeter is the constant string '->'. The third parameter is the value returned by the cmp function, which must be fully evaluated before strcat can return.

  • The cmp function takes 5 arguments (x, y, lt, eq, gt). It compares x and y and returns the third argument lt if x < y, the fourth argument eq if x == y, and the fifth argument gt if x > y. As with all functions, all of the parameters can be statements. In this case the first parameter (the value for x) is the result of dividing the series_index by 2. The second parameter y is the constant 1. The third parameter lt is a statement (more later). The fourth parameter eq is the constant string 'eq'. The fifth parameter is the constant string 'gt'.

  • The third parameter (the one for lt) is a statement, or a sequence of expressions. Remember that a statement (a sequence of semicolon-separated expressions) is also an expression, returning the value of the last expression in the list. In this case, the program first assigns the value 1 to a local variable c, then returns a substring made by extracting the c’th character to the end. Since c always contains the constant 1, the substring will return the second through end’th characters, or 't123'.

  • Once the statement providing the value to the third parameter is executed, cmp can return a value. At that point, strcat` can return a value, then ``substr can return a value. The program then terminates.

For various values of series_index, the program returns:

  • series_index == undefined, result = prefix ->t123 suffix

  • series_index == 0.5, resultado = prefix 0.50-> suffix

  • series_index == 1, resultado = prefix 1->t12 suffix

  • series_index == 2, resultado = prefix 2->eq suffix

  • series_index == 3, resultado = prefix 3->gt suffix

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

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

  • and(value, value, ...) – returns the string «1» if all values are 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.

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

  • assign(id, val) – atribui VAL a ID, e depois devolve VAL. ID deve ser um identificador e não uma expressão

  • 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) – returns a string containing a list of authors and that author’s link values in the form author1 val_separator author1link pair_separator author2 val_separator author2link etc. An author is separated from its link value by the val_separator string with no added spaces. author:linkvalue pairs are separated by the pair_separator string argument with no added spaces. It is up to you to choose separator strings that do not occur in author names or links. An author is included even if the author link is empty.

  • author_sorts(val_separator) – returns a string containing a list of author’s sort values for the authors of the book. The sort is the one in the author metadata (different from the author_sort in books). The returned list has the form author sort 1 val_separator author sort 2 etc. The author sort values in this list are in the same order as the authors of the book. If you want spaces around val_separator then include them in the separator string

  • booksize() – returns the value of the calibre “size” field. Returns “” if there are no formats.

  • check_yes_no(field_name, is_undefined, is_false, is_true) – checks the value of the yes/no field named by the lookup key field_name for a value specified by the parameters, returning «yes» if a match is found, otherwise returning an empty string. Set the parameter is_undefined, is_false, or is_true to 1 (the number) to check that condition, otherwise set it to 0. Example:

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

    returns «yes» if the yes/no field "#bool" is either undefined (neither True nor False) or True. More than one of is_undefined, is_false, or is_true can be set to 1. This function is usually used by the test() or is_empty() functions.

  • ceiling(x) – returns the smallest integer greater than or equal to x. Throws an exception if x is not a number.

  • cmp(x, y, lt, eq, gt) – compares x and y after converting both to numbers. Returns lt if x < y. Returns eq if x == y. Otherwise returns gt.

  • 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) – return the number of days between date1 and date2. The number is positive if date1 is greater than date2, otherwise negative. If either date1 or date2 are not dates, the function returns the empty string.

  • 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) – returns the metadata field named by 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", " - ", " - ")
    

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

    program:
        strcat(
            re(field('series'), '([^\s])[^\s]+(\s|$)', '\1'),
            finish_formatting(field('series_index'), '0>2s', ' - ', ' - '),
            field('title')
        )
    
  • 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.

  • floor(x) – returns the largest integer less than or equal to x. Throws an exception if x is not a number.

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

  • formats_modtimes(format_string) – cria uma lista, separada por vírgulas, de itens separados por dois pontos que representam horas de alteração para os formatos de um livro. O parâmetro date_format especifica como a data deve ser formatada. Ver a função format_date() para mais detalhes. Pode usar a função de seleção para obter a hora de alteração para um formato específico. Note que os nomes dos formatos são sempre em maiúsculas, tal como em EPUB.

  • formats_paths() – cria uma lista de itens, separados por dois pontos, que representam o caminho completo para os formatos de um livro. Pode usar a função de seleção para obter o caminho para um formato específico. Note que os nomes dos formatos são sempre em maiúsculas, tal como em EPUB.

  • formats_sizes() – cria uma lista de itens separados por dois pontos que representam tamanhos em bytes dos formatos de um livro. Pode usar a função de seleção para obter o tamanho de um formato específico. Note que os nomes dos formatos são sempre em maiúsculas, tal como em 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() – devolve Yes se o livro possuir capa, caso contrário devolve uma expressão vazia

  • 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) – devolve uma lista feita ao remover da list1 qualquer item encontrado em list2, usando uma comparação não sensível a maiúsculas. Os itens em list1 e list2 são separados por separador, tal como estão os itens da lista devolvida.

  • list_equals(list1, sep1, list2, sep2, yes_val, no_val) – devolverá yes_val se list1 e list2 contiverem os mesmos itens, caso contrário devolverá no_val. Os itens são determinados dividindo cada lista usando o carácter separador apropriado (sep1 ou sep2). A ordem dos itens das listas não é relevante. A comparação não é sensível a maiúsculas.

  • list_intersection(list1, list2, separator) – devolve uma lista feita ao remover da list1 qualquer item não encontrado em list2, usando uma comparação não sensível a maiúsculas. Os itens em list1 e list2 são separados por separador, tal como estão os itens da lista devolvida.

  • list_re(src_list, separator, include_re, opt_replace) – Construir uma lista, primeiro pela separação de src_list em itens usando o carácter separator. Para cada item da lista, verificar se ele corresponde a include_re. Se isso acontecer, então adicioná-lo à lista a ser obtida. Se opt_replace não for uma string vazia, então aplicar a substituição antes de adicionar o item à lista obtida.

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

  • list_sort(list, direction, separator) – devolve uma lista ordenada usando uma ordenação não diferenciadora de maiúsculas. Se direction for zero, a lista é ordenada de forma crescente, caso contrário será por ordem decrescente. Os itens da lista são separados por separator, tal como o são os itens na lista devolvida.

  • list_union(list1, list2, separator) – devolve uma lista feita pela fusão dos itens da list1 e list2, removendo itens duplicados sendo usada uma comparação não sensível a maiúsculas. Se os itens diferirem em maiúsculas, é usado o primeiro da list1. Os itens em list1 e list2 são separados pelo separador, tal como estão os itens da lista devolvida.

  • 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) – returns x * y. Throws an exception if either x or y are not numbers.

  • ondevice() – return the string «Yes» if ondevice is set, otherwise return the empty string

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

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

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

  • raw_list(name, separator) – devolve a lista de metadados por nomeado por nome mas sem aplicar formatações ou ordenação e com itens separados por separator.

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

    {series:'re_group($, "(\S* )(.*)", "[[$:uppercase()]]", "[[$]]")'}
    
  • round(x) – returns the nearest integer to x. Throws an exception if x is not a number.

  • series_sort() – devolve o valor de ordenação da série.

  • strcat(a, b, ...) – pode receber qualquer número de argumentos. Devolve uma expressão formada pela concatenação de todos os argumentos.

  • strcat_max(max, string1, prefix2, string2, ...) – Devolve uma expressão formada pela concatenação dos argumentos. O valor devolvido é inicializado para string1. Pares Prefix, string são adicionados ao final do valor desde que o comprimento da expressão resultante seja inferior a max. String1 será devolvida mesmo se string1 for maior que max. Pode passar quantos pares prefix, string quiser.

  • strcmp(x, y, lt, eq, gt) – faz uma comparação intensiva não diferenciadora de maiúsculas de x e y como strings. Devolve lt se x < y. Devolve eq se x == y. Caso contrário devolve gt.

  • strlen(a) – Devolve o comprimento do texto passando-o como um argumento.

  • substr(str, start, end) – devolve start’th pelos caracteres end’th de str. O primeiro carácter str é o carácter zero’th. Se end for negativo, então indica esse número de caracteres contados da direita. Se end for zero, então indica o último carácter. Por exemplo, substr('12345', 1, 0) devolve '2345', e substr('12345', 1, -1) devolve '234'.

  • subtract(x, y) – devolve x - y. Devolve uma exceção se x ou y não forem números.

  • today() – devolve uma string com a data de hoje. Este valor é destinado ao uso em format_date e days_between, mas pode ser manipulado como qualquer outra string. A data está em formato ISO.

  • template(x) – analisa x como um modelo. A analise é feita em seu próprio contexto, o que significa que as variáveis não são compartilhadas entre a chamador e a análise do modelo. Como os caracteres { e } são especiais, deve usar [[ para { e ]] para “}”. Serão convertidos automaticamente. Por exemplo,``template(“[[title_sort]]”) irá analisar o modelo {title_sort} e devolver o seu valor. Note também que prefixos e sufixos (a sintaxwe |prefix|suffix ) não podem ser usados no argumento para esta função ao usar o modo de programação de modelos.

Function classification

Usar modo de programação geral

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

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

Both General and Template Program Modes support if tests with the following syntax:
  • if <<expression>> then <<expression_list>> [ else <<expression_list>> ] fi.

The else part is optional. The words if, then, 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

Program mode also supports the 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Funções de modelos definidas por utilizador

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.

Notas especiais para modelos de exportar/enviar

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

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

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

A barra inclinada e o hífen aparecem apenas se a série não estiver vazia.

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

Para obter isto, fazemos:
  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.

Modelos e quadros de conexões

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

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

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

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

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

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

  • um quadro de conexões para qualquer formato e qualquer dispositivo

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

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

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

Dicas úteis

Poderá achar úteis as seguintes dicas.

  • Create a custom composite column to test templates. Once you have the column, you can change its template simply by double-clicking on the column. Hide the column when you are not testing.

  • Templates can use other templates by referencing a composite custom column.

  • In a plugboard, you can set a field to empty (or whatever is equivalent to empty) by using the special template {}. This template will always evaluate to an empty string.

  • The technique described above to show numbers even if they have a zero value works with the standard field series_index.