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ósfrom_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_link¶
- class calibre.utils.formatter_functions.BuiltinGetLink[código-fonte]¶
get_link(field_name, field_value)
– busca o link para o campo field_name
com valor field_value
. Se não houver um link anexado, retorna a string vazia. Exemplos:
O seguinte retorna o link anexado à tag
Fiction
:get_link('tags', 'Fiction')
Este modelo faz uma lista dos links para todas as tags associadas a um livro no formato
value:link, ...
:program: ans = ''; for t in $tags: l = get_link('tags', t); if l then ans = list_join(', ', ans, ',', t & ':' & get_link('tags', t), ',') fi rof; ans
Esta função funciona 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 valorfield_value
no campofield_name
tiver uma nota, caso contrário''
.Exemplo:
has_note('tags', 'Fiction')
retorna'1'
se a tagfiction
tiver uma nota anexada, caso contrário''
.Se
field_value
for''
então retorne uma lista de valores emfield_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
: adicionev
segundos adate
m
: adicionev
minutos adate
h
: adicionev
horas adate
d
: adicionev
dias adate
w
: adicionev
semanas adate
y
: adicionev
anos adate
, 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.
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