Reference for all built-in template language functions

Here, we document all the built-in functions available in the calibre template language. Every function is implemented as a class in python and you can click the source links to see the source code, in case the documentation is insufficient. The functions are arranged in logical groups by type.

Alteração de maiúsculas/minúsculas

capitalize

class calibre.utils.formatter_functions.BuiltinCapitalize[código-fonte]

capitalize(value) – devolve o valor de value com a primeira letra em maísuculas e as restantes em minúsculas.

lowercase

class calibre.utils.formatter_functions.BuiltinLowercase[código-fonte]

lowercase(value) – devolve o valor de value em minúsculas.

titlecase

class calibre.utils.formatter_functions.BuiltinTitlecase[código-fonte]

titlecase(value) – devolve o valor de value no formato caixa de título.

uppercase

class calibre.utils.formatter_functions.BuiltinUppercase[código-fonte]

uppercase(value) – devolve o valor de value em maísculas.

Aritmético

add

class calibre.utils.formatter_functions.BuiltinAdd[código-fonte]

add(x [,y]*) — devolve a soma dos seus argumentos.. Lança uma exceção se um argumento não for um número. Esta função pode, muitas vezes, ser substituída pelo operador +.

ceiling

class calibre.utils.formatter_functions.BuiltinCeiling[código-fonte]

ceiling(value) — devolve o menor número inteiro que seja maior que ou igual a value. Devolve uma exceção se value não for um número.

divide

class calibre.utils.formatter_functions.BuiltinDivide[código-fonte]

divide(x, y) — devolve x - y. Devolve uma exceção se x ou y não forem números. Esta função pode, muitas vezes, ser substituída pelo operador / .

floor

class calibre.utils.formatter_functions.BuiltinFloor[código-fonte]

floor(value) — devolve o maior número inteiro que seja menor que ou igual a value. Devolve uma exceção se value não for um número.

fractional_part

class calibre.utils.formatter_functions.BuiltinFractionalPart[código-fonte]

fractional_part(value) — devolve o valor existente depois da casa decimal. Por exemplo, fractional_part(3.14) devolve 0.14. Lança uma exceção caso value não seja um número.

mod

class calibre.utils.formatter_functions.BuiltinMod[código-fonte]

mod(value, y) — devolve o floor do remanascente de value / y. Devolve uma exceção se value ou y não forem números.

multiply

class calibre.utils.formatter_functions.BuiltinMultiply[código-fonte]

multiply(x [,y]*) – devolve o produto de seus argumentos. Devolve uma exceção se um argumento não for um número. Esta função pode, muitas vezes, ser substituída pelo operador *.

round

class calibre.utils.formatter_functions.BuiltinRound[código-fonte]

round(value) — devolve o número inteiro mais próximo de value. Devolve uma exceção se value não for um número.

subtract

class calibre.utils.formatter_functions.BuiltinSubtract[código-fonte]

subtract(x, y) — devolve x - y. Devolve uma exceção se x ou y não forem números. Esta função pode, muitas vezes, ser substituída pelo operador - .

Booleano

and

class calibre.utils.formatter_functions.BuiltinAnd[código-fonte]

and(value [, value]*) – retorna a string '1' se todos os valores não estiverem vazios, caso contrário, retorna a string vazia. Você pode ter quantos valores quiser. Na maioria dos casos, você pode usar o operador && em vez desta função. Um motivo para não substituir and() por && é quando o curto-circuito pode alterar os resultados por causa de efeitos colaterais. Por exemplo, and(a='',b=5) sempre fará ambas as atribuições, onde o operador && não fará a segunda.

not

class calibre.utils.formatter_functions.BuiltinNot[código-fonte]

not(value) – retorna a string '1' se o valor estiver vazio, caso contrário retorna a string vazia. Esta função geralmente pode ser substituída pelo operador unário not (!).

or

class calibre.utils.formatter_functions.BuiltinOr[código-fonte]

or(value [, value]*) – retorna a string '1' se algum valor não estiver vazio, caso contrário, retorna a string vazia. Você pode ter quantos valores quiser. Esta função geralmente pode ser substituída pelo operador ||. Um motivo pelo qual ela não pode ser substituída é se o curto-circuito mudará os resultados por causa de efeitos colaterais.

Formatação de valores

finish_formatting

class calibre.utils.formatter_functions.BuiltinFinishFormatting[código-fonte]

finish_formatting(value, format, prefix, suffix) – aplica format, prefix e suffix ao value da mesma forma que é feito em um modelo como {series_index:05.2f| - |- }. Esta função é fornecida para facilitar a conversão de modelos complexos de função única ou de modo de programa de modelo para modelos GPM. Por exemplo, o programa a seguir produz a mesma saída que o modelo acima :

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

Outro exemplo: para o modelo:

{series:re(([^\s])[^\s]+(\s|$),\1)}{series_index:0>2s| - | - }{título}
[/CÓDIGO]
uso:
[CODE]
programa:
strcat(
re(campo('série'), '([^\s])[^\s]+(\s|$)', '\1'),
finish_formatting(campo('índice_de_série'), '0>2s', ' - ', ' - '),
campo('título')
)

format_date

class calibre.utils.formatter_functions.BuiltinFormatDate[código-fonte]

format_date(value, format_string) – formata o value, que deve ser uma string de data, usando o format_string, retornando uma string. É melhor se a data estiver no formato ISO, pois usar outros formatos de data geralmente causa erros porque o valor real da data não pode ser determinado de forma inequívoca. Observe que a função format_date_field() é mais rápida e confiável.

Os códigos de formatação são:

  • d : o dia como número sem zero à esquerda (1 a 31)

  • dd : o dia como número com zero à esquerda (01 a 31)

  • ddd : o nome abreviado do dia localizado (por exemplo, “Seg” a “Dom”).

  • dddd : o nome longo do dia localizado (por exemplo, “Segunda” a “Domingo”).

  • M : o mês como número sem um zero à esquerda (1 a 12).

  • MM : o mês como número com um zero à esquerda (01 a 12)

  • MMM : o nome abreviado do mês localizado (por exemplo, “Jan” a “Dez”).

  • MMMM : o nome longo do mês localizado (por exemplo, “Janeiro” a “Dezembro”).

  • yy : o ano como número de dois dígitos (00 a 99).

  • yyyy : o ano como número de quatro dígitos.

  • h : as horas sem um 0 inicial (0 a 11 ou 0 a 23, dependendo de am/pm)

  • hh : as horas com um 0 inicial (00 a 11 ou 00 a 23, dependendo de am/pm)

  • m : os minutos sem um 0 inicial (0 a 59)

  • mm : os minutos com um 0 inicial (00 a 59)

  • s : os segundos sem um 0 inicial (0 a 59)

  • ss : os segundos com um 0 inicial (00 a 59)

  • ap : use um relógio de 12 horas em vez de um relógio de 24 horas, com ‘ap’ substituído pela string localizada para am ou pm.

  • AP : use um relógio de 12 horas em vez de um relógio de 24 horas, com ‘AP’ substituído pela string localizada para AM ou PM.

  • iso : a data com hora e fuso horário. Deve ser o único formato presente.

  • to_number : converta a data e a hora em um número de ponto flutuante (um timestamp)

  • from_number : converta um número de ponto flutuante (um timestamp) em uma data formatada em ISO. Se você quiser um formato de data diferente, adicione a string de formatação desejada após from_number e dois pontos (:). Exemplo:

    format_date(val, 'from_number:MMM dd yyyy')
    

Você pode obter resultados inesperados se a data que você está formatando contiver nomes de meses localizados, o que pode acontecer se você alterou o formato da data para conter MMMM. Usar format_date_field() evita esse problema.

format_date_field

class calibre.utils.formatter_functions.BuiltinFormatDateField[código-fonte]

format_date_field(field_name, format_string) – formata o valor no campo field_name, que deve ser o nome de pesquisa de um campo de data, padrão ou personalizado. Veja format_date() para os códigos de formatação. Esta função é muito mais rápida que format_date() e deve ser usada quando você estiver formatando o valor em um campo (coluna). Também é mais confiável porque funciona diretamente na data subjacente. Não pode ser usada para datas computadas ou datas em variáveis ​​de string. Exemplos:

format_date_field('pubdate', 'yyyy.MM.dd')
format_date_field('#date_read', 'MMM dd, yyyy')

format_number

class calibre.utils.formatter_functions.BuiltinFormatNumber[código-fonte]

format_number(value, template) – interpreta o value como um número e formata esse número usando um modelo de formatação Python como {0:5.2f} ou {0:,d} ou ${0:5,.2f}. O modelo de formatação deve começar com {0: e terminar com } como nos exemplos acima. Exceção: você pode deixar de fora o “{0:” inicial e o “}” final se o modelo de formato contiver apenas um formato. Veja a Linguagem de modelo e a documentação do Python para mais exemplos. Retorna a string vazia se a formatação falhar.

human_readable

class calibre.utils.formatter_functions.BuiltinHumanReadable[código-fonte]

human_readable(value) – espera que o value seja um número e retorna uma string representando esse número em KB, MB, GB, etc.

rating_to_stars

class calibre.utils.formatter_functions.BuiltinRatingToStars[código-fonte]

rating_to_stars(value, use_half_stars) – Retorna o value como uma sequência de caracteres de estrela (). O valor deve ser um número entre 0 e 5. Defina use_half_stars como 1 se quiser caracteres de meia estrela para números fracionários disponíveis com colunas de classificação personalizadas.

urls_from_identifiers

class calibre.utils.formatter_functions.BuiltinUrlsFromIdentifiers[código-fonte]

urls_from_identifiers(identifiers, sort_results) – dada uma lista separada por vírgulas de identificadores, onde um identificador é um par de valores separados por dois pontos (id_name:id_value), retorna uma lista separada por vírgulas de URLs HTML geradas a partir dos identificadores. A lista não é classificada se sort_results for 0 (caractere ou número), caso contrário, é classificada alfabeticamente pelo nome do identificador. Os URLs são gerados da mesma forma que a coluna de identificadores incorporada quando mostrada em Detalhes do livro.

Funções de banco de dados

book_count

class calibre.utils.formatter_functions.BuiltinBookCount[código-fonte]

book_count(query, use_vl) – retorna a contagem de livros encontrados ao pesquisar por query. Se use_vl for 0 (zero), as bibliotecas virtuais serão ignoradas. Esta função e sua companheira book_values() são particularmente úteis em pesquisas de modelo, suportando pesquisas que combinam informações de muitos livros como procurar por séries com apenas um livro. Ela não pode ser usada em colunas compostas, a menos que o ajuste allow_template_database_functions_in_composites esteja definido como True. Ela pode ser usada apenas na GUI.

Por exemplo, esta pesquisa de modelo usa esta função e sua companheira para encontrar todas as séries com apenas um livro:

  • Defina um modelo armazenado (usando Preferences → Advanced → Template functions) chamado series_only_one_book (o nome é arbitrário). O modelo é:

    programa:
    vals = globals(vals='');
    if !vals then
    all_series = book_values('series', 'series:true', ',', 0);
    for series in all_series:
    if book_count('series:="' & series & '"', 0) == 1 then
    vals = list_join(',', vals, ',', series, ',')
    fi
    rof;
    set_globals(vals)
    fi;
    str_in_list(vals, ',', $series, 1, '')
    [/CÓDIGO]
    A primeira vez que o modelo é executado (o primeiro livro verificado), ele armazena os resultados
    das pesquisas no banco de dados em uma variável de modelo ``global`` chamada ``vals``. Esses
    resultados são usados ​​para verificar livros subsequentes sem refazer as pesquisas.
    [*] Use o modelo armazenado em uma pesquisa de modelo:
    [CODE]
    template:"program: series_only_one_book()#@#:n:1"
    

    Usar um modelo armazenado em vez de colocar o modelo na pesquisa elimina problemas causados ​​pela exigência de escapar aspas em expressões de pesquisa.

Esta função pode ser usada apenas na GUI e no servidor de conteúdo.

book_values

class calibre.utils.formatter_functions.BuiltinBookValues[código-fonte]

book_values(column, query, sep, use_vl) – retorna uma lista dos valores únicos contidos na coluna column (um nome de pesquisa), separados por sep, nos livros encontrados pela pesquisa por query. Se use_vl for 0 (zero) então as bibliotecas virtuais serão ignoradas. Esta função e sua companheira book_count() são particularmente úteis em pesquisas de modelo, suportando pesquisas que combinam informações de muitos livros, como procurar por séries com apenas um livro. Ela não pode ser usada em colunas compostas, a menos que o ajuste allow_template_database_functions_in_composites esteja definido como True. Esta função pode ser usada apenas na GUI e no servidor de conteúdo.

extra_file_modtime

class calibre.utils.formatter_functions.BuiltinExtraFileModtime[código-fonte]

extra_file_modtime(file_name, format_string) – retorna o tempo de modificação do arquivo extra file_name na pasta data/ do livro se ele existir, caso contrário -1. O modtime é formatado de acordo com format_string (veja format_date() para detalhes). Se format_string for a string vazia, retorna o modtime como o número de segundos em ponto flutuante desde a época. Veja também as funções has_extra_files(), extra_file_names() e extra_file_size(). A época depende do SO. Esta função pode ser usada apenas na GUI e no servidor de conteúdo.

extra_file_names

class calibre.utils.formatter_functions.BuiltinExtraFileNames[código-fonte]

extra_file_names(sep [, pattern]) – retorna uma lista separada por sep de arquivos extras na pasta data/ do livro. Se o parâmetro opcional pattern, uma expressão regular, for fornecido, a lista será filtrada para arquivos que correspondem a pattern. A correspondência de padrão não diferencia maiúsculas de minúsculas. Veja também as funções has_extra_files(), extra_file_modtime() e extra_file_size(). Esta função pode ser usada apenas na GUI e no servidor de conteúdo.

extra_file_size

class calibre.utils.formatter_functions.BuiltinExtraFileSize[código-fonte]

extra_file_size(file_name) – retorna o tamanho em bytes do arquivo extra file_name na pasta data/ do livro se existir, caso contrário -1. Veja também as funções has_extra_files(), extra_file_names() e extra_file_modtime(). Esta função pode ser usada apenas na GUI e no servidor de conteúdo.

get_note

class calibre.utils.formatter_functions.BuiltinGetNote[código-fonte]

get_note(field_name, field_value, plain_text) – busca a nota para o campo field_name com o valor field_value. Se plain_text estiver vazio, retorna o HTML da nota incluindo imagens. Se plain_text for 1 (ou '1'), retorna o texto simples da nota. Se a nota não existir, retorna a string vazia em ambos os casos. Exemplo:

  • Retorna o HTML da nota anexada à tag Fiction:

    program:
    get_note('tags', 'Fiction', '')
    
  • Retorna o texto simples da nota anexada ao autor Isaac Asimov:

    program:
    get_note('authors', 'Isaac Asimov', 1)
    

Esta função funciona apenas na GUI e no servidor de conteúdo.

has_extra_files

class calibre.utils.formatter_functions.BuiltinHasExtraFiles[código-fonte]

has_extra_files([pattern]) – retorna a contagem de arquivos extras, caso contrário ‘’ (a string vazia). Se o parâmetro opcional pattern (uma expressão regular) for fornecido, a lista será filtrada para arquivos que correspondem a pattern antes que os arquivos sejam contados. A correspondência de padrão não diferencia maiúsculas de minúsculas. Veja também as funções extra_file_names(), extra_file_size() e extra_file_modtime(). Esta função pode ser usada apenas na GUI e no servidor de conteúdo.

has_note

class calibre.utils.formatter_functions.BuiltinHasNote[código-fonte]

has_note(field_name, field_value). Verifique se um campo tem uma nota. Esta função tem duas variantes:

  • se field_value não for '' (a string vazia) retorne '1' se o valor field_value no campo field_name tiver uma nota, caso contrário ''.

    Exemplo: has_note('tags', 'Fiction') retorna '1' se a tag fiction tiver uma nota anexada, caso contrário ''.

  • Se field_value for '' então retorne uma lista de valores em field_name que tenham uma nota. Se nenhum item no campo tiver uma nota, retorne ''. Esta variante é útil para mostrar ícones de coluna se qualquer valor no campo tiver uma nota, em vez de um valor específico.

    Exemplo: has_note('authors', '') retorna uma lista de autores que têm notas, ou '' se nenhum autor tiver uma nota.

Você pode testar se todos os valores em field_name têm uma nota comparando o comprimento da lista do valor de retorno desta função com o comprimento da lista dos valores em field_name. Exemplo:

list_count(has_note('authors', ''), '&') ==# list_count_field('authors')

Esta função funciona apenas na GUI e no servidor de conteúdo.

Funções de data

date_arithmetic

class calibre.utils.formatter_functions.BuiltinDateArithmetic[código-fonte]

date_arithmetic(value, calc_spec, fmt) – Calcula uma nova data a partir de value usando calc_spec. Retorna a nova data formatada de acordo com o opcional fmt: se não for fornecido, o resultado estará no formato ISO. calc_spec é uma string formada pela concatenação de pares de vW (valueWhat) onde v é um número possivelmente negativo e W é uma das seguintes letras:

  • s: adicione v segundos a date

  • m: adicione v minutos a date

  • h: adicione v horas a date

  • d: adicione v dias a date

  • w: adicione v semanas a date

  • y: adicione v anos a date, onde um ano tem 365 dias.

Exemplo: '1s3d-1m' adicionará 1 segundo, adicionará 3 dias e subtrairá 1 minuto de date.

days_between

class calibre.utils.formatter_functions.BuiltinDaysBetween[código-fonte]

days_between(date1, date2) – retorna o número de dias entre date1 e date2. O número é positivo se date1 for maior que date2, caso contrário, negativo. Se date1 ou date2 não forem datas, a função retorna a string vazia.

today

class calibre.utils.formatter_functions.BuiltinToday[código-fonte]

today() – retorna uma string de data+hora para hoje (agora). Este valor é projetado para uso em format_date ou days_between, mas pode ser manipulado como qualquer outra string. A data está no formato ISO data/hora.

Manipulação de listas

list_count

class calibre.utils.formatter_functions.BuiltinCount[código-fonte]

list_count(value, separator) – interpreta o valor como uma lista de itens separados por separator e retorna o número de itens na lista. A maioria das listas usa uma vírgula como separador, mas authors usa um e comercial (&).

Exemplos: {tags:list_count(,)}, {authors:list_count(&)}.

Aliases: count(), list_count()

list_count_field

class calibre.utils.formatter_functions.BuiltinFieldListCount[código-fonte]

list_count_field(lookup_name)– retorna a contagem de itens no campo com o nome de lookup lookup_name. O campo deve ser multivalorado, como authors ou tags, caso contrário, a função gera um erro. Esta função é muito mais rápida que list_count() porque opera diretamente em dados do calibre sem convertê-los em uma string primeiro. Exemplo: list_count_field('tags').

list_count_matching

class calibre.utils.formatter_functions.BuiltinListCountMatching[código-fonte]

list_count_matching(value, pattern, separator) – interpreta value como uma lista de itens separados por separator, retornando o número de itens na lista que correspondem à expressão regular pattern.

Aliases: list_count_matching(), count_matching()

list_difference

class calibre.utils.formatter_functions.BuiltinListDifference[código-fonte]

list_difference(list1, list2, separator) – retorna uma lista feita removendo de list1 qualquer item encontrado em list2 usando uma comparação sem distinção entre maiúsculas e minúsculas. Os itens em list1 e list2 são separados por separator, assim como os itens na lista retornada.

list_equals

class calibre.utils.formatter_functions.BuiltinListEquals[código-fonte]

list_equals(list1, sep1, list2, sep2, yes_val, no_val) – retorna yes_val se list1 e list2 contiverem os mesmos itens, caso contrário, retorna no_val. Os itens são determinados pela divisão de cada lista usando o caractere separador apropriado (sep1 ou sep2). A ordem dos itens nas listas não é relevante. A comparação não diferencia maiúsculas de minúsculas.

list_intersection

class calibre.utils.formatter_functions.BuiltinListIntersection[código-fonte]

list_intersection(list1, list2, separator) – retorna uma lista feita removendo de list1 qualquer item não encontrado em list2, usando uma comparação sem distinção entre maiúsculas e minúsculas. Os itens em list1 e list2 são separados por separator, assim como os itens na lista retornada.

list_join

class calibre.utils.formatter_functions.BuiltinListJoin[código-fonte]

list_join(with_separator, list1, separator1 [, list2, separator2]*) – retorna uma lista feita juntando os itens nas listas de origem (list1 etc) usando with_separator entre os itens na lista de resultados. Itens em cada origem list[123...] são separados pelo separator[123...] associado. Uma lista pode conter zero valores. Pode ser um campo como publisher que é de valor único, efetivamente uma lista de um item. Duplicatas são removidas usando uma comparação que não diferencia maiúsculas de minúsculas. Itens são retornados na ordem em que aparecem nas listas de origem. Se itens em listas diferem apenas em letras maiúsculas, então a última é usada. Todos os separadores podem ter mais de um caractere.

Exemplo:

programa:
list_join('#@#', $authors, '&', $tags, ',')

Você pode usar list_join nos resultados de chamadas anteriores para list_join da seguinte forma:

programa:
a = list_join('#@#', $authors, '&', $tags, ',');
b = list_join('#@#', a, '#@#', $#genre, ',', $#people, '&', 'some value', ',')

Você pode usar expressões para gerar uma lista. Por exemplo, suponha que você queira itens para authors e #genre, mas com o gênero alterado para a palavra “Genre: “ seguido pela primeira letra do gênero, ou seja, o gênero “Fiction” se torna “Genre: F”. O seguinte fará isso:

program:
    list_join('#@#', $authors, '&', list_re($#genre, ',', '^(.).*$', 'Genre: \1'),  ',')

list_re

class calibre.utils.formatter_functions.BuiltinListRe[código-fonte]

list_re(src_list, separator, include_re, opt_replace) – Construa uma lista primeiro separando src_list em itens usando o caractere separator. Para cada item na lista, verifique se ele corresponde a include_re. Se corresponder, adicione-o à lista a ser retornada. Se opt_replace não for a string vazia, então aplique a substituição antes de adicionar o item à lista retornada.

list_re_group

class calibre.utils.formatter_functions.BuiltinListReGroup[código-fonte]

list_re_group(src_list, separator, include_re, search_re [,template_for_group]*) – Como list_re, exceto que as substituições não são opcionais. Ele usa re_group(item, search_re, template ...) ao fazer as substituições.

list_remove_duplicates

class calibre.utils.formatter_functions.BuiltinListRemoveDuplicates[código-fonte]

list_remove_duplicates(list, separator) – retorna uma lista feita removendo itens duplicados em list. Se os itens diferem apenas em caso, o último é retornado. Os itens em list são separados por separator, assim como os itens na lista retornada.

list_sort

class calibre.utils.formatter_functions.BuiltinListSort[código-fonte]

list_sort(value, direction, separator) – retorna value classificado usando uma classificação lexical sem distinção entre maiúsculas e minúsculas. Se direction for zero (número ou caractere), value é classificado em ordem crescente, caso contrário, em ordem decrescente. Os itens da lista são separados por separator, assim como os itens na lista retornada.

list_split

class calibre.utils.formatter_functions.BuiltinListSplit[código-fonte]

list_split(list_val, sep, id_prefix) — separa list_val em valores separados usando sep, e então atribui os valores a variáveis nomeadas id_prefix_N onde N é a posição do valor na lista. O primeiro item tem uma posição 0 (zero). A função devolve o último elemento da lista.

Exemplo:

list_split('one:two:foo', ':', 'var')

is equivalent to:

var_0 = 'one'
var_1 = 'two'
var_2 = 'foo'

list_union

class calibre.utils.formatter_functions.BuiltinListUnion[código-fonte]

list_union(list1, list2, separator) – retorna uma lista feita pela fusão dos itens em list1 e list2, removendo itens duplicados usando uma comparação que não diferencia maiúsculas de minúsculas. Se os itens diferem em maiúsculas e minúsculas, o de list1 é usado. Os itens em list1 e list2 são separados por separator, assim como os itens na lista retornada. Aliases: merge_lists(), list_union()

range

class calibre.utils.formatter_functions.BuiltinRange[código-fonte]

range(start, stop, step, limit) – retorna uma lista de números gerados por looping sobre o intervalo especificado pelos parâmetros start, stop e step, com um comprimento máximo de limit. O primeiro valor produzido é ‘start’. Valores subsequentes next_v = current_v + step. O loop continua enquanto next_v < stop assumindo que step é positivo, caso contrário, enquanto next_v > stop. Uma lista vazia é produzida se start falhar no teste: start >= stop se step for positivo. O limit define o comprimento máximo da lista e tem um padrão de 1000. Os parâmetros start, step e limit são opcionais. Chamar range() com um argumento especifica stop. Dois argumentos especificam start e stop. Três argumentos especificam start, stop e step. Quatro argumentos especificam start, stop, step e limit.

Exemplos:

range(5) -> '0, 1, 2, 3, 4'
range(0, 5) -> '0, 1, 2, 3, 4'
range(-1, 5) -> '-1, 0, 1, 2, 3, 4'
range(1, 5) -> '1, 2, 3, 4'
range(1, 5, 2) -> '1, 3'
range(1, 5, 2, 5) -> '1, 3'
range(1, 5, 2, 1) -> erro(limite excedido)

subitems

class calibre.utils.formatter_functions.BuiltinSubitems[código-fonte]

subitems(value, start_index, end_index) – Esta função separa listas de itens hierárquicos semelhantes a tags, como gêneros. Ela interpreta o value como uma lista separada por vírgulas de itens semelhantes a tags, onde cada item é uma lista separada por ponto. Ela retorna uma nova lista feita extraindo de cada item os componentes de start_index a end_index, e então mesclando os resultados novamente. Duplicatas são removidas. O primeiro subitem em uma lista separada por ponto tem um índice de zero. Se um índice for negativo, ele conta a partir do fim da lista. Como um caso especial, um end_index de zero é assumido como o comprimento da lista.

Exemplos:

  • Supondo uma coluna #genre contendo “A.B.C”:

    • {#genre:subitems(0,1)} retorna “A”

    • {#genre:subitems(0,2)} retorna “A.B”

    • {#genre:subitems(1,0)} retorna “B.C”

  • Supondo uma coluna #genre contendo “A.B.C, D.E”:

    • {#genre:subitems(0,1)} retorna “A, D”

    • {#genre:subitems(0,2)} retorna “A.B, D.E”

sublist

class calibre.utils.formatter_functions.BuiltinSublist[código-fonte]

sublist(value, start_index, end_index, separator) – interpreta o value como uma lista de itens separados por separator, retornando uma nova lista feita a partir dos itens de start_index a end_index. O primeiro item é o número zero. Se um índice for negativo, então ele conta a partir do fim da lista. Como um caso especial, um end_index de zero é assumido como o comprimento da lista.

Exemplos assumindo que a coluna tags (que é separada por vírgulas) contém “A, B, C”:

  • {tags:sublist(0,1,\,)} retorna “A”

  • {tags:sublist(-1,0,\,)} retorna “C”

  • {tags:sublist(0,-1,\,)} retorna “A, B”

Manipulação de strings

character

class calibre.utils.formatter_functions.BuiltinCharacter[código-fonte]

character(character_name) – retorna o caractere nomeado por character_name. Por exemplo, character('newline') retorna um caractere de nova linha ('\n'). Os nomes de caracteres suportados são newline, return, tab e backslash. Esta função é usada para colocar esses caracteres na saída de modelos.

check_yes_no

class calibre.utils.formatter_functions.BuiltinCheckYesNo[código-fonte]

check_yes_no(field_name, is_undefined, is_false, is_true) – verifica se o valor do campo sim/não nomeado pelo nome de pesquisa field_name é um dos valores especificados pelos parâmetros, retornando 'Sim' se uma correspondência for encontrada caso contrário, retornando a string vazia. Defina o parâmetro is_undefined, is_false ou is_true como 1 (o número) para verificar essa condição, caso contrário, defina-o como 0.

Exemplo: check_yes_no("#bool", 1, 0, 1) retorna 'Sim' se o campo sim/não #bool for Verdadeiro ou indefinido (nem Verdadeiro nem Falso).

Mais de um de is_undefined, is_false ou is_true pode ser definido como 1.

Esta função funciona apenas na GUI e no servidor de conteúdo.

contains

class calibre.utils.formatter_functions.BuiltinContains[código-fonte]

contains(value, pattern, text_if_match, text_if_not_match) – verifica se o valor é correspondido pela expressão regular pattern. Retorna text_if_match se o padrão corresponde ao valor, caso contrário retorna text_if_not_match.

field_exists

class calibre.utils.formatter_functions.BuiltinFieldExists[código-fonte]

field_exists(lookup_name) – verifica se um campo (coluna) com o nome de pesquisa lookup_name existe, retornando '1' se sim e a string vazia se não.

ifempty

class calibre.utils.formatter_functions.BuiltinIfempty[código-fonte]

ifempty(value, text_if_empty) – se o value não estiver vazio, então retorne esse value, caso contrário, retorne text_if_empty.

re

class calibre.utils.formatter_functions.BuiltinRe[código-fonte]

re(value, pattern, replacement) – retorna o value após aplicar a expressão regular. Todas as instâncias de pattern no valor são substituídas por replacement. A linguagem de modelo usa expressões Python regulares que não diferenciam maiúsculas de minúsculas.

re_group

class calibre.utils.formatter_functions.BuiltinReGroup[código-fonte]

re_group(value, pattern [, template_for_group]*) – retorna uma string feita aplicando a expressão regular pattern a value e substituindo cada instância correspondente pelo valor retornado pelo template correspondente. No Template Program Mode, como para as funções template e eval, você usa [[ para { e ]] para }.

O exemplo a seguir procura uma série com mais de uma palavra e coloca a primeira palavra em maiúscula:

program: re_group(field('series'), "(\S* )(.*)", "{$:uppercase()}", "{$}")'}

shorten

class calibre.utils.formatter_functions.BuiltinShorten[código-fonte]

shorten(value, left_chars, middle_text, right_chars) – Return a shortened version of the value, consisting of left_chars characters from the beginning of the value, followed by middle_text, followed by right_chars characters from the end of the value. left_chars and right_chars must be non-negative integers.

Example: assume you want to display the title with a length of at most 15 characters in length. One template that does this is {title:shorten(9,-,5)}. For a book with the title Ancient English Laws inthe Times of Ivanhoe the result will be Ancient E-anhoe: the first 9 characters of the title, a -, then the last 5 characters. If the value’s length is less than left chars + right chars + the length of middle text then the value will be returned unchanged. For example, the title TheDome would not be changed.

Mostrando a documentação em inglês devido ao erro FFML: Missing closing “``” for CODE_TEXT on line 12 in “shorten”

strcat

class calibre.utils.formatter_functions.BuiltinStrcat[código-fonte]

strcat(a [, b]*) — devolve uma sequência formada pela concatenação dos seus argumentos. Pode receber qualquer número de argumentos. Esta função pode, muitas vezes, ser substituída pelo operador &.

strcat_max

class calibre.utils.formatter_functions.BuiltinStrcatMax[código-fonte]

strcat_max(max, string1 [, prefix2, string2]*) – Retorna uma string formada pela concatenação dos argumentos. O valor retornado é inicializado como string1. Strings feitas de pares prefix, string são adicionadas ao final do valor, desde que o comprimento da string resultante seja menor que max. Prefixos podem estar vazios. Retorna string1 mesmo se string1 for maior que max. Você pode passar quantos pares prefix, string desejar.

strlen

class calibre.utils.formatter_functions.BuiltinStrlen[código-fonte]

strlen(value) – Devolve o comprimento da sequência value.

substr

class calibre.utils.formatter_functions.BuiltinSubstr[código-fonte]

substr(value, start, end) – retorna o start’ésimo até o end’ésimo caracteres de value. O primeiro caractere em value é o zero’ésimo caractere. Se end for negativo, então indica que muitos caracteres estão sendo contados da direita. Se end for zero, então indica o último caractere. Por exemplo, substr('12345', 1, 0) retorna '2345', e substr('12345', 1, -1) retorna '234'.

swap_around_articles

class calibre.utils.formatter_functions.BuiltinSwapAroundArticles[código-fonte]

swap_around_articles(value, separator) – retorna o value com artigos movidos para o fim. O value pode ser uma lista, em que caso cada item na lista é processado. Se o value for uma lista, então você deve fornecer o separator. Se nenhum separator for fornecido, então o value é tratado como sendo um único valor, não uma lista. Os articles são aqueles usados ​​pelo calibre para gerar o title_sort.

swap_around_comma

class calibre.utils.formatter_functions.BuiltinSwapAroundComma[código-fonte]

swap_around_comma(value) – dado um value do formato B, A, retorna A B. Isso é mais útil para converter nomes no formato LN, FN para FN LN. Se não houver uma vírgula no value, a função retorna o valor inalterado.

test

class calibre.utils.formatter_functions.BuiltinTest[código-fonte]

test(value, text_if_not_empty, text_if_empty) — devolve text_if_not_empty` se o valor não estiver vazio, caso contrário devolve ``text_if_empty`.

to_hex

class calibre.utils.formatter_functions.BuiltinToHex[código-fonte]

to_hex(val) – retorna a string val codificada em hexadecimal. Isso é útil ao construir URLs de calibre.

transliterate

class calibre.utils.formatter_functions.BuiltinTransliterate[código-fonte]

transliterate(value) – Retorna uma string em um alfabeto latino formada pela aproximação do som das palavras em value. Por exemplo, se value for Фёдор Миха́йлович Достоевский esta função retorna Fiodor Mikhailovich Dostoievskii.

Obter valores dos metadados

annotation_count

class calibre.utils.formatter_functions.BuiltinAnnotationCount[código-fonte]

annotation_count() – retorna o número total de anotações de todos os tipos anexadas ao livro atual. Esta função funciona apenas na GUI e no servidor de conteúdo.

approximate_formats

class calibre.utils.formatter_functions.BuiltinApproximateFormats[código-fonte]

approximate_formats() – retorna uma lista separada por vírgulas de formatos associados ao livro. Como a lista vem do banco de dados do calibre em vez do sistema de arquivos, não há garantia de que a lista esteja correta, embora provavelmente esteja. Observe que os nomes dos formatos resultantes são sempre maiúsculos, como no EPUB. A função approximate_formats() é muito mais rápida do que as funções formats_... .

Esta função funciona apenas na GUI. Se você quiser usar esses valores em modelos de salvar em disco ou enviar para o dispositivo, você deve criar uma “Coluna criada a partir de outras colunas” personalizada, usar a função no modelo dessa coluna e usar o valor dessa coluna em seus modelos de salvar/enviar.

author_sorts

class calibre.utils.formatter_functions.BuiltinAuthorSorts[código-fonte]

author_sorts(val_separator) – retorna uma string contendo uma lista de valores de classificação do autor para os autores do livro. A classificação é aquela nas informações de metadados do autor, que pode ser diferente do author_sort em livros. A lista retornada tem o formato author sort 1 val_separator author sort 2 etc. sem espaços adicionados. Os valores de classificação do autor nesta lista estão na mesma ordem que os autores do livro. Se você quiser espaços ao redor de val_separator então inclua-os na string val_separator.

booksize

class calibre.utils.formatter_functions.BuiltinBooksize[código-fonte]

booksize() – retorna o valor do campo size do calibre. Retorna ‘’ se o livro não tiver formatos.

Esta função funciona apenas na GUI. Se você quiser usar este valor em modelos de salvar em disco ou enviar para o dispositivo, então você deve criar uma “Coluna criada a partir de outras colunas” personalizada, usar a função no modelo dessa coluna e usar o valor dessa coluna em seus modelos de salvar/enviar

connected_device_name

class calibre.utils.formatter_functions.BuiltinConnectedDeviceName[código-fonte]

connected_device_name(storage_location_key) – se um dispositivo estiver conectado, então retorna o nome do dispositivo, caso contrário, retorna a string vazia. Cada local de armazenamento em um dispositivo tem seu próprio nome de dispositivo. Os nomes storage_location_key são 'main', 'carda' e 'cardb'. Esta função funciona apenas na GUI.

connected_device_uuid

class calibre.utils.formatter_functions.BuiltinConnectedDeviceUUID[código-fonte]

connected_device_uuid(storage_location_key) – se um dispositivo estiver conectado, então retorna o uuid do dispositivo (id exclusivo), caso contrário, retorna a string vazia. Cada local de armazenamento em um dispositivo tem um uuid diferente. Os nomes de localização storage_location_key são 'main', 'carda' e 'cardb'. Esta função funciona somente na GUI.

current_library_name

class calibre.utils.formatter_functions.BuiltinCurrentLibraryName[código-fonte]

current_library_name() – devolve último nome no caminho para a biblioteca atual do Calibre.

current_library_path

class calibre.utils.formatter_functions.BuiltinCurrentLibraryPath[código-fonte]

current_library_path() – devolve caminho completo para a biblioteca atual do Calibre.

current_virtual_library_name

class calibre.utils.formatter_functions.BuiltinCurrentVirtualLibraryName[código-fonte]

current_virtual_library_name() – retorna o nome da biblioteca virtual atual se houver uma, caso contrário, a string vazia. O caso do nome da biblioteca é preservado. Exemplo:

program: current_virtual_library_name()

Esta função funciona apenas na GUI.

field

class calibre.utils.formatter_functions.BuiltinField[código-fonte]

field(lookup_name) – retorna o valor do campo de metadados com o nome de pesquisa lookup_name. O prefixo $ pode ser usado em vez da função, como em $tags.

formats_modtimes

class calibre.utils.formatter_functions.BuiltinFormatsModtimes[código-fonte]

formats_modtimes(date_format_string) – retorna uma lista separada por vírgulas de itens separados por dois pontos FMT:DATE representando horários de modificação para os formatos de um livro. O parâmetro date_format_string especifica como a data deve ser formatada. Veja a função format_date() para detalhes. Você pode usar a função select() para obter o horário de modificação para um formato específico. Observe que os nomes de formato são sempre maiúsculos, como no EPUB.

formats_paths

class calibre.utils.formatter_functions.BuiltinFormatsPaths[código-fonte]

formats_paths() – retorna uma lista separada por vírgulas de itens separados por dois pontos FMT:PATH fornecendo o caminho completo para os formatos de um livro. Você pode usar a função select() para obter o caminho para um formato específico. Observe que os nomes de formato são sempre maiúsculos, como em EPUB.

formats_sizes

class calibre.utils.formatter_functions.BuiltinFormatsSizes[código-fonte]

formats_sizes() – retorna uma lista separada por vírgulas de itens FMT:SIZE separados por dois pontos, fornecendo os tamanhos dos formatos de um livro em bytes. Você pode usar a função select() para obter o tamanho de um formato específico. Observe que os nomes dos formatos são sempre maiúsculos, como em EPUB.

has_cover

class calibre.utils.formatter_functions.BuiltinHasCover[código-fonte]

has_cover() – devolve 'Yes' se o livro possuir capa, caso contrário devolve uma expressão vazia.

is_marked

class calibre.utils.formatter_functions.BuiltinIsMarked[código-fonte]

is_marked() – verifica se o livro está marcado no calibre. Se estiver, então retorna o valor da marca, seja 'true' (letras minúsculas) ou uma lista separada por vírgulas de marcas nomeadas. Retorna '' (a string vazia) se o livro não estiver marcado. Esta função funciona apenas na GUI.

language_codes

class calibre.utils.formatter_functions.BuiltinLanguageCodes[código-fonte]

language_codes(lang_strings) – retorna os códigos de idioma para os nomes de idioma passados ​​em lang_strings. As strings devem estar no idioma do local atual. lang_strings é uma lista separada por vírgulas.

language_strings

class calibre.utils.formatter_functions.BuiltinLanguageStrings[código-fonte]

language_strings(value, localize) – retorna os nomes de idioma para os códigos de idioma (veja aqui para nomes e códigos) passados ​​em value. Exemplo: {languages:language_strings()}. Se localize for zero, retorna as strings em inglês. Se localize não for zero, retorna as strings no idioma do local atual. lang_codes é uma lista separada por vírgulas.

ondevice

class calibre.utils.formatter_functions.BuiltinOndevice[código-fonte]

ondevice() – retorna a string 'Sim' se ondevice estiver definido, caso contrário retorna a string vazia. Esta função funciona apenas na GUI. Se você quiser usar este valor em modelos de salvar em disco ou enviar para o dispositivo, então você deve criar uma “Coluna personalizada construída a partir de outras colunas”, usar a função no modelo dessa coluna e usar o valor dessa coluna em seus modelos de salvar/enviar.

raw_field

class calibre.utils.formatter_functions.BuiltinRawField[código-fonte]

raw_field(lookup_name [, optional_default]) – retorna o campo de metadados nomeado por lookup_name sem aplicar nenhuma formatação. Ele avalia e retorna o segundo argumento opcional optional_default se o valor do campo for indefinido (None). O prefixo $$ pode ser usado em vez da função, como em $$pubdate.

raw_list

class calibre.utils.formatter_functions.BuiltinRawList[código-fonte]

raw_list(lookup_name, separator) — devolve a lista de metadados nomeada por lookup_name mas sem aplicar qualquer formatação ou ordenação e com itens separados por separator.

series_sort

class calibre.utils.formatter_functions.BuiltinSeriesSort[código-fonte]

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

user_categories

class calibre.utils.formatter_functions.BuiltinUserCategories[código-fonte]

user_categories() – retorna uma lista separada por vírgulas das categorias de usuário que contêm este livro. Esta função funciona apenas na GUI. Se você quiser usar esses valores em modelos de salvar em disco ou enviar para o dispositivo, então você deve criar uma Coluna personalizada construída a partir de outras colunas, usar a função no modelo dessa coluna, e usar o valor dessa coluna em seus modelos de salvar/enviar

virtual_libraries

class calibre.utils.formatter_functions.BuiltinVirtualLibraries[código-fonte]

virtual_libraries() – retorna uma lista separada por vírgulas de bibliotecas virtuais que contêm este livro. Esta função funciona apenas na GUI. Se você quiser usar esses valores em modelos de salvar em disco ou enviar para dispositivo, então você deve criar uma “Coluna criada a partir de outras colunas” personalizada, usar a função no modelo dessa coluna, e usar o valor dessa coluna em seus modelos de salvar/enviar. Esta função funciona apenas na GUI.

Outro

arguments

class calibre.utils.formatter_functions.BuiltinArguments[código-fonte]

arguments(id[=expression] [, id[=expression]]*) – Usado em um template armazenado para recuperar os argumentos passados ​​na chamada. Ele declara e inicializa variáveis ​​locais com os nomes fornecidos, os id``s, tornando-os efetivamente parâmetros. As variáveis ​​são posicionais; elas obtêm o valor do argumento fornecido na chamada na mesma posição. Se o argumento correspondente não for fornecido na chamada, então ``arguments() atribui a essa variável o valor padrão fornecido. Se não houver valor padrão, então a variável é definida para a string vazia.

assign

class calibre.utils.formatter_functions.BuiltinAssign[código-fonte]

assign(id, val) — atribui value a id e depois devolve value. O id deve ser um identificador e não uma expressão. Esta função pode, muitas vezes, ser substituída pelo operador =

globals

class calibre.utils.formatter_functions.BuiltinGlobals[código-fonte]

globals(id[=expression] [, id[=expression]]*) – Recupera “variáveis ​​globais” que podem ser passadas para o formatador. O nome id é o nome da variável global. Ele declara e inicializa variáveis ​​locais com os nomes das variáveis ​​globais passadas (os parâmetros id. Se a variável correspondente não for fornecida nos globais, então ele atribui a essa variável o valor padrão fornecido. Se não houver valor padrão, então a variável é definida para a string vazia.)

is_dark_mode

class calibre.utils.formatter_functions.BuiltinIsDarkMode[código-fonte]

is_dark_mode() – retorna '1' se o calibre estiver rodando no modo escuro, '' (a string vazia) caso contrário. Esta função pode ser usada em regras avançadas de cores e ícones para escolher cores/ícones diferentes de acordo com o modo. Exemplo:

if is_dark_mode() then 'dark.png' else 'light.png' fi

print

class calibre.utils.formatter_functions.BuiltinPrint[código-fonte]

print(a [, b]*) — imprime os argumentos para a saída predefinida. A menos que vá iniciar o Calibre a partir da linha de comandos (calibre-debug -g), a saída irá parar a um buraco negro. A função print devlve sempre o primeiro argumento.

set_globals

class calibre.utils.formatter_functions.BuiltinSetGlobals[código-fonte]

set_globals(id[=expression] [, id[=expression]]*) – Define variáveisglobais que podem ser passadas para o formatador. Os globais recebem o nome do id passado. O valor do id é usado a menos que uma expressão seja fornecida.

Pesquisa de listas

identifier_in_list

class calibre.utils.formatter_functions.BuiltinIdentifierInList[código-fonte]

identifier_in_list(val, id_name [, found_val, not_found_val]) – trata val como uma lista de identificadores separados por vírgulas. Um identificador tem o formato id_name:value. O parâmetro id_name é o texto id_name a pesquisar, seja id_name ou id_name:regexp. O primeiro caso corresponde se houver algum identificador que corresponda a esse id_name. O segundo caso corresponde se id_name corresponder a um identificador e o regexp corresponder ao valor do identificador. Se found_val e not_found_val forem fornecidos, então se houver uma correspondência, então retorne found_val, caso contrário, retorne not_found_val. Se found_val e not_found_val não forem fornecidos, então, se houver uma correspondência, retorne o par identificador:valor, caso contrário, a string vazia ('').

list_contains

class calibre.utils.formatter_functions.BuiltinInList[código-fonte]

list_contains(value, separator, [ pattern, found_val, ]* not_found_val) – interpreta o value como uma lista de itens separados por separator, verificando o pattern contra cada item na lista. Se o pattern corresponder a um item, então retorne found_val, caso contrário, retorne not_found_val. O par pattern e found_value pode ser repetido quantas vezes desejar, permitindo retornar valores diferentes dependendo do valor do item. Os padrões são verificados em ordem, e a primeira correspondência é retornada.

Aliases: in_list(), list_contains()

list_item

class calibre.utils.formatter_functions.BuiltinListitem[código-fonte]

list_item(value, index, separator) – interpreta o value como uma lista de itens separados por separator, retornando o ‘index’ésimo item. O primeiro item é o número zero. O último item tem o índice -1 como em list_item(-1,separator). Se o item não estiver na lista, então a string vazia é retornada. O separador tem o mesmo significado que na função count, geralmente vírgula, mas é e comercial para listas do tipo autor.

select

class calibre.utils.formatter_functions.BuiltinSelect[código-fonte]

select(value, key) – interpreta o value como uma lista de itens separados por vírgulas com cada item tendo o formato id:id_value (o formato identifier do calibre). A função encontra o primeiro par com o id igual a key e retorna o id_value correspondente. Se nenhum id corresponder, a função retorna a string vazia.

str_in_list

class calibre.utils.formatter_functions.BuiltinStrInList[código-fonte]

str_in_list(value, separator, [ string, found_val, ]+ not_found_val) – interpreta o value como uma lista de itens separados por separator e então compara string com cada valor na lista. A string não é uma expressão regular. Se string for igual a qualquer item (ignorando maiúsculas e minúsculas), então retorna o correspondente found_val. Se string contiver separators, então também é tratado como uma lista e cada subvalor é verificado. Os pares string e found_value podem ser repetidos quantas vezes forem desejadas, permitindo retornar valores diferentes dependendo do valor da string. Se nenhuma das strings corresponder, então not_found_value é retornado. As strings são verificadas em ordem. A primeira correspondência é retornada.

Recorrência

eval

class calibre.utils.formatter_functions.BuiltinEval[código-fonte]

eval(string) – avalia a string como um programa, passando as variáveis locais. Isso permite usar o processador de modelo para construir resultados complexos a partir de variáveis ​​locais. No Modo de Programa de Modelo, porque os caracteres { e } são interpretados antes que o modelo seja avaliado, você deve usar [[ para o caractere { e ]] para o caractere } . Eles são convertidos automaticamente. Observe também que prefixos e sufixos (a sintaxe |prefix|suffix) não podem ser usados ​​no argumento para esta função ao usar o Modo de Programa de Modelo.

template

class calibre.utils.formatter_functions.BuiltinTemplate[código-fonte]

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 partilhadas entre a chamador e a análise do modelo. Se não usar o modo de Programação geral, e porque os caracteres { e } são especiais, deve usar [[ para { e ]] para o carácter }. 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 por modelos.

Relacional

cmp

class calibre.utils.formatter_functions.BuiltinCmp[código-fonte]

cmp(value, y, lt, eq, gt) – compares value and y after converting both to numbers. Returns lt if value <# y, eq if value ==# y, otherwise gt. This function can usually be replaced with one of the numeric compare operators (==#, <#, >#, etc).

Mostrando a documentação em inglês devido ao erro FFML: Missing closing “`” for italics on line 2 in “cmp”

first_matching_cmp

class calibre.utils.formatter_functions.BuiltinFirstMatchingCmp[código-fonte]

first_matching_cmp(val, [ cmp, result, ]* else_result) — compara val < cmp em sequência, devolvendo o result associado para a primeira comparação com sucesso. Devolve else_result se não houver comparações com sucesso. Exemplo:

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

devolve "large". O mesmo exemplo, mas em que o primeiro valor seja 16, devolve "giant".

strcmp

class calibre.utils.formatter_functions.BuiltinStrcmp[código-fonte]

strcmp(x, y, lt, eq, gt) — faz uma comparação lexical, não diferenciadora de maiúsculas, de x e y. Devolve lt se x < y. Devolve eq se x == y. Caso contrário devolve gt. Esta função pode ser substituída, em muitos casos, por um dos operadores de comparação lexical (==, >, <, etc.)

strcmpcase

class calibre.utils.formatter_functions.BuiltinStrcmpcase[código-fonte]

strcmpcase(x, y, lt, eq, gt) — faz uma comparação lexical entre x e y com diferenciação entre maiúsculas e minúsculas. Devolve lt se x < y. Devolve eq se x == y. De contrário devolve gt. Nota: Este NÃO é o comportamento predefinido usado pelo Calibre, por exemplo, nos operadores de comparação léxical (==, >, <, etc.). Esta função pode causar resultados inesperados. Utilize strcmp() sempre que possível.

Repetir sobre valores

first_non_empty

class calibre.utils.formatter_functions.BuiltinFirstNonEmpty[código-fonte]

first_non_empty(value [, value]*) – retorna o primeiro value que não está vazio. Se todos os valores estiverem vazios, a string vazia será retornada. Você pode ter quantos valores quiser.

lookup

class calibre.utils.formatter_functions.BuiltinLookup[código-fonte]

lookup(value, [ pattern, key, ]* else_key) – Os padrões serão verificados em relação ao value em ordem. Se um pattern corresponder, o valor do campo nomeado por key será retornado. Se nenhum padrão corresponder, o valor do campo nomeado por else_key será retornado. Veja também a função switch().

switch

class calibre.utils.formatter_functions.BuiltinSwitch[código-fonte]

switch(value, [patternN, valueN,]+ else_value) – para cada par patternN, valueN, verifica se o value corresponde à expressão regular patternN e, se for o caso, retorna o valueN associado. Se nenhum patternN corresponder, então else_value é retornado. Você pode ter quantos pares patternN, valueN desejar. A primeira correspondência é retornada.

switch_if

class calibre.utils.formatter_functions.BuiltinSwitchIf[código-fonte]

switch_if([test_expression, value_expression,]+ else_expression) – para cada par test_expression, value_expression, verifica se test_expression é True (não vazio) e, se for, retorna o resultado de value_expression. Se nenhuma test_expression for True, o resultado de else_expression é retornado. Você pode ter quantos pares test_expression, value_expression quiser.

API of the Metadata objects

The python implementation of the template functions is passed in a Metadata object. Knowing it’s API is useful if you want to define your own template functions.

class calibre.ebooks.metadata.book.base.Metadata(title, authors=('Desconhecido',), other=None, template_cache=None, formatter=None)[código-fonte]

A class representing all the metadata for a book. The various standard metadata fields are available as attributes of this object. You can also stick arbitrary attributes onto this object.

Metadata from custom columns should be accessed via the get() method, passing in the lookup name for the column, for example: “#mytags”.

Use the is_null() method to test if a field is null.

This object also has functions to format fields into strings.

The list of standard metadata fields grows with time is in STANDARD_METADATA_FIELDS.

Please keep the method based API of this class to a minimum. Every method becomes a reserved field name.

is_null(field)[código-fonte]

Return True if the value of field is null in this object. ‘null’ means it is unknown or evaluates to False. So a title of _(‘Unknown’) is null or a language of ‘und’ is null.

Be careful with numeric fields since this will return True for zero as well as None.

Also returns True if the field does not exist.

deepcopy(class_generator=<function Metadata.<lambda>>)[código-fonte]

Do not use this method unless you know what you are doing, if you want to create a simple clone of this object, use deepcopy_metadata() instead. Class_generator must be a function that returns an instance of Metadata or a subclass of it.

get_identifiers()[código-fonte]

Return a copy of the identifiers dictionary. The dict is small, and the penalty for using a reference where a copy is needed is large. Also, we don’t want any manipulations of the returned dict to show up in the book.

set_identifiers(identifiers)[código-fonte]

Set all identifiers. Note that if you previously set ISBN, calling this method will delete it.

set_identifier(typ, val)[código-fonte]

If val is empty, deletes identifier of type typ

standard_field_keys()[código-fonte]

return a list of all possible keys, even if this book doesn’t have them

custom_field_keys()[código-fonte]

return a list of the custom fields in this book

all_field_keys()[código-fonte]

All field keys known by this instance, even if their value is None

metadata_for_field(key)[código-fonte]

return metadata describing a standard or custom field.

all_non_none_fields()[código-fonte]

Return a dictionary containing all non-None metadata fields, including the custom ones.

get_standard_metadata(field, make_copy)[código-fonte]

return field metadata from the field if it is there. Otherwise return None. field is the key name, not the label. Return a copy if requested, just in case the user wants to change values in the dict.

get_all_standard_metadata(make_copy)[código-fonte]

return a dict containing all the standard field metadata associated with the book.

get_all_user_metadata(make_copy)[código-fonte]

return a dict containing all the custom field metadata associated with the book.

get_user_metadata(field, make_copy)[código-fonte]

return field metadata from the object if it is there. Otherwise return None. field is the key name, not the label. Return a copy if requested, just in case the user wants to change values in the dict.

set_all_user_metadata(metadata)[código-fonte]

store custom field metadata into the object. Field is the key name not the label

set_user_metadata(field, metadata)[código-fonte]

store custom field metadata for one column into the object. Field is the key name not the label

remove_stale_user_metadata(other_mi)[código-fonte]

Remove user metadata keys (custom column keys) if they don’t exist in ‘other_mi’, which must be a metadata object

template_to_attribute(other, ops)[código-fonte]

Takes a list [(src,dest), (src,dest)], evaluates the template in the context of other, then copies the result to self[dest]. This is on a best-efforts basis. Some assignments can make no sense.

smart_update(other, replace_metadata=False)[código-fonte]

Merge the information in other into self. In case of conflicts, the information in other takes precedence, unless the information in other is NULL.

format_field(key, series_with_index=True)[código-fonte]

Returns the tuple (display_name, formatted_value)

to_html()[código-fonte]

A HTML representation of this object.

calibre.ebooks.metadata.book.base.STANDARD_METADATA_FIELDS

The set of standard metadata fields.


'''
All fields must have a NULL value represented as None for simple types,
an empty list/dictionary for complex types and (None, None) for cover_data
'''

SOCIAL_METADATA_FIELDS = frozenset((
    'tags',             # Ordered list
    'rating',           # A floating point number between 0 and 10
    'comments',         # A simple HTML enabled string
    'series',           # A simple string
    'series_index',     # A floating point number
    # Of the form { scheme1:value1, scheme2:value2}
    # For example: {'isbn':'123456789', 'doi':'xxxx', ... }
    'identifiers',
))

'''
The list of names that convert to identifiers when in get and set.
'''

TOP_LEVEL_IDENTIFIERS = frozenset((
    'isbn',
))

PUBLICATION_METADATA_FIELDS = frozenset((
    'title',            # title must never be None. Should be _('Unknown')
    # Pseudo field that can be set, but if not set is auto generated
    # from title and languages
    'title_sort',
    'authors',          # Ordered list. Must never be None, can be [_('Unknown')]
    'author_sort_map',  # Map of sort strings for each author
    # Pseudo field that can be set, but if not set is auto generated
    # from authors and languages
    'author_sort',
    'book_producer',
    'timestamp',        # Dates and times must be timezone aware
    'pubdate',
    'last_modified',
    'rights',
    # So far only known publication type is periodical:calibre
    # If None, means book
    'publication_type',
    'uuid',             # A UUID usually of type 4
    'languages',        # ordered list of languages in this publication
    'publisher',        # Simple string, no special semantics
    # Absolute path to image file encoded in filesystem_encoding
    'cover',
    # Of the form (format, data) where format is, e.g. 'jpeg', 'png', 'gif'...
    'cover_data',
    # Either thumbnail data, or an object with the attribute
    # image_path which is the path to an image file, encoded
    # in filesystem_encoding
    'thumbnail',
))

BOOK_STRUCTURE_FIELDS = frozenset((
    # These are used by code, Null values are None.
    'toc', 'spine', 'guide', 'manifest',
))

USER_METADATA_FIELDS = frozenset((
    # A dict of dicts similar to field_metadata. Each field description dict
    # also contains a value field with the key #value#.
    'user_metadata',
))

DEVICE_METADATA_FIELDS = frozenset((
    'device_collections',   # Ordered list of strings
    'lpath',                # Unicode, / separated
    'size',                 # In bytes
    'mime',                 # Mimetype of the book file being represented
))

CALIBRE_METADATA_FIELDS = frozenset((
    'application_id',   # An application id, currently set to the db_id.
    'db_id',            # the calibre primary key of the item.
    'formats',          # list of formats (extensions) for this book
    # a dict of user category names, where the value is a list of item names
    # from the book that are in that category
    'user_categories',
    # a dict of items to associated hyperlink
    'link_maps',
))

ALL_METADATA_FIELDS =      SOCIAL_METADATA_FIELDS.union(
                           PUBLICATION_METADATA_FIELDS).union(
                           BOOK_STRUCTURE_FIELDS).union(
                           USER_METADATA_FIELDS).union(
                           DEVICE_METADATA_FIELDS).union(
                           CALIBRE_METADATA_FIELDS)

# All fields except custom fields
STANDARD_METADATA_FIELDS = SOCIAL_METADATA_FIELDS.union(
                           PUBLICATION_METADATA_FIELDS).union(
                           BOOK_STRUCTURE_FIELDS).union(
                           DEVICE_METADATA_FIELDS).union(
                           CALIBRE_METADATA_FIELDS)

# Metadata fields that smart update must do special processing to copy.
SC_FIELDS_NOT_COPIED =     frozenset(('title', 'title_sort', 'authors',
                                      'author_sort', 'author_sort_map',
                                      'cover_data', 'tags', 'languages',
                                      'identifiers'))

# Metadata fields that smart update should copy only if the source is not None
SC_FIELDS_COPY_NOT_NULL =  frozenset(('device_collections', 'lpath', 'size', 'comments', 'thumbnail'))

# Metadata fields that smart update should copy without special handling
SC_COPYABLE_FIELDS =       SOCIAL_METADATA_FIELDS.union(
                           PUBLICATION_METADATA_FIELDS).union(
                           BOOK_STRUCTURE_FIELDS).union(
                           DEVICE_METADATA_FIELDS).union(
                           CALIBRE_METADATA_FIELDS) - \
                           SC_FIELDS_NOT_COPIED.union(
                           SC_FIELDS_COPY_NOT_NULL)

SERIALIZABLE_FIELDS =      SOCIAL_METADATA_FIELDS.union(
                           USER_METADATA_FIELDS).union(
                           PUBLICATION_METADATA_FIELDS).union(
                           CALIBRE_METADATA_FIELDS).union(
                           DEVICE_METADATA_FIELDS) - \
                           frozenset(('device_collections', 'formats',
                               'cover_data'))
# these are rebuilt when needed