.. _templaterefcalibre-es: 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. .. contents:: :depth: 2 :local: .. module:: calibre.utils.formatter_functions Aritméticas -------------------------------------------- .. _ff_add: add ^^^ .. class:: BuiltinAdd ``add(x [, y]*)`` -- devuelve la suma de sus argumentos. Da un error si algún argumento no es un número. En la mayoría de los casos puede usarse el operador ``+`` en lugar de esta función. .. _ff_ceiling: ceiling ^^^^^^^ .. class:: BuiltinCeiling ``ceiling(valor)`` -- devuelve el menor entero que es mayor o igual a ``valor``. Da un error si ``valor`` no es un número. .. _ff_divide: divide ^^^^^^ .. class:: BuiltinDivide ``divide(x, y)`` -- devuelve ``x / y``. Da un error si ``x`` o ``y`` no son números. Esta función puede sustituirse a menudo por el operador ``/``. .. _ff_floor: floor ^^^^^ .. class:: BuiltinFloor ``floor(valor)`` -- devuelve el mayor entero que es menor o igual a ``valor``. Da un error si ``valor`` no es un número. .. _ff_fractional_part: fractional_part ^^^^^^^^^^^^^^^ .. class:: BuiltinFractionalPart ``fractional_part(valor)`` -- devuelve la parte del valor tras el punto decimal. Por ejemplo, ``fractional_part(3.14)`` devuelve ``0.14``. Da un error si ``valor`` no es un número. .. _ff_mod: mod ^^^ .. class:: BuiltinMod ``mod(valor, y)`` -- devuelve ``floor`` del resto de ``valor / y``. Da un error si ``valor`` o ``y`` no son números. .. _ff_multiply: multiply ^^^^^^^^ .. class:: BuiltinMultiply ``multiply(x [, y]*)`` -- devuelve el producto de sus argumentos. Da un error si algún argumento no es un número. Esta función puede sustituirse a menudo por el operador ``*``. .. _ff_round: round ^^^^^ .. class:: BuiltinRound ``round(valor)`` -- devuelve el entero más cercano a ``valor``. Da un error si ``valor`` no es un número. .. _ff_subtract: subtract ^^^^^^^^ .. class:: BuiltinSubtract ``subtract(x, y)`` -- devuelve ``x - y``. Da un error si ``x`` o ``y`` no son números. Esta función puede sustituirse a menudo por el operador ``-``. Cambio de mayúsculas y minúsculas ------------------------------------------------------------------------------------------------------------------------------------ .. _ff_capitalize: capitalize ^^^^^^^^^^ .. class:: BuiltinCapitalize ``capitalize(valor)`` -- devuelve ``valor`` con la primera letra mayúscula y el resto en minúsculas. .. _ff_lowercase: lowercase ^^^^^^^^^ .. class:: BuiltinLowercase ``lowercase(valor)`` -- devuelve ``valor`` en minúsculas. .. _ff_titlecase: titlecase ^^^^^^^^^ .. class:: BuiltinTitlecase ``titlecase(valor)`` -- devuelve ``valor`` con las iniciales en mayúscula. .. _ff_uppercase: uppercase ^^^^^^^^^ .. class:: BuiltinUppercase ``uppercase(valor)`` -- devuelve ``valor`` en mayúsculas. Consulta de listas ------------------------------------------------------------------------ .. _ff_identifier_in_list: identifier_in_list ^^^^^^^^^^^^^^^^^^ .. class:: BuiltinIdentifierInList ``identifier_in_list(val, nombre_id [, val_encontrado, val_no_encontrado])`` -- trata ``val`` como una lista de identificadores separados por comas. Un identificador tiene el formato ``nombre_id:valor``. El parámetro ``nombre_id`` es el texto de nombre de identificador a buscar, ya sea ``nombre_id`` o ``nombre_id:expreg``. El primer caso coincide si hay algún identificador con ese nombre. El segundo caso coincide si algún identificador tiene ese nombre y la expresión regular coincide con el valor del identificador. Si se proporcionan ``val_encontrado`` y ``val_no_encontrado``, si hay una coincidencia, se devuelve ``val_encontrado``; de lo contrario, se devuelve ``val_no_encontrado``. Si ``val_encontrado`` y ``val_no_encontrado`` están ausentes, si hay alguna coincidencia, se devuelve el par ``identificador:valor``; de lo contrario, el texto vacío (``''``). .. _ff_list_contains: list_contains ^^^^^^^^^^^^^ .. class:: BuiltinInList ``list_contains(valor, separador, [ patrón, encontrado, ]* no_encontrado)`` -- interpreta ``valor`` como una lista de elementos separados por ``separador`` y comprueba ``patrón`` para cada elemento de la lista. Si ``patrón`` coincide con algún elemento, devuelve ``encontrado``, en caso contrario devuelve ``no_encontrado``. La pareja de argumentos ``patrón`` y ``encontrado`` puede repetirse tantas veces como se desee, lo que permite devolver diferentes valores según el valor del elemento. Los patrones se evalúan en orden y se devuelve la primera coincidencia. Sinónimos: in_list(), list_contains() .. _ff_list_item: list_item ^^^^^^^^^ .. class:: BuiltinListitem ``list_item(valor, índice, separador)`` -- interpreta ``valor`` como una lista de elementos separados po ``separador`` y devuelve el elemento número ``índice``. El primer elemento es el número cero. El último elemento puede obtenerse con ``list_item(-1, separador)``. Si el elemento no está en la lista devuelve un texto vacío. El separador tiene el mismo significado que en la función ``count``, normalmente una coma pero es un carácter «&» en listas de tipo autor. .. _ff_select: select ^^^^^^ .. class:: BuiltinSelect ``select(valor, clave)`` -- interpreta ``valor`` como una lista de elementos separados por comas, con cada elemento de la forma ``id:valor_id`` (el formato de la columna ``identifier`` de calibre). La función encuentra la primera pareja con ``id`` igual a ``clave`` y devuelve el ``valor_id`` correspondiente. Si no se encuentra el ``id`` la función devuelve un texto vacío. .. _ff_str_in_list: str_in_list ^^^^^^^^^^^ .. class:: BuiltinStrInList ``str_in_list(valor, separador, [ texto, encontrado, ]+ no_encontrado)`` -- interpreta ``valor`` como una lista de elementos separados por ``separador``, y compara ``texto`` con cada valor de la lista. El argumento ``texto`` no es una expresión regular. Si ``texto`` es igual a alguno de los valores (sin distinción de mayúsculas y minúsculas), devuelve el correspondiente ``encontrado``. Si ``texto`` contiene ``separador``, se interpreta también como una lista y se compara cada subvalor. La pareja de argumentos ``texto`` y ``encontrado`` puede repetirse tantas veces como se desee, lo que permite devolver diferentes valores según el valor de ``texto``. Los textos se comparan en orden. Se devuelve la primera coincidencia. Formato de valores ------------------------------------------------------------------------ .. _ff_finish_formatting: finish_formatting ^^^^^^^^^^^^^^^^^ .. class:: BuiltinFinishFormatting ``finish_formatting(valor, formato, prefijo, sufijo)`` -- aplica el ``formato``, ``prefijo`` y ``sufijo`` a ``valor`` de la misma manera que se haría en una plantilla como ``{series_index:05.2f| - |- }``. Esta función se proporciona para facilitar la conversión de plantillas complejas en modo de función única o de plantilla a plantillas `MPG`. Por ejemplo, el siguiente programa produce la misma salida que la plantilla anterior: :: program: finish_formatting(field("series_index"), "05.2f", " - ", " - ") Otro ejemplo: para la plantilla: :: {series:re(([^\s])[^\s]+(\s|$),\1)}{series_index:0>2s| - | - }{title} se puede usar: :: program: strcat( re(field('series'), '([^\s])[^\s]+(\s|$)', '\1'), finish_formatting(field('series_index'), '0>2s', ' - ', ' - '), field('title') ) .. _ff_format_date: format_date ^^^^^^^^^^^ .. class:: BuiltinFormatDate ``format_date(valor, texto_formato)`` -- da formato a ``valor``, que debe ser un campo de fecha, según ``texto_formato`` y devuelve un texto. Lo mejor es que la fecha esté en formato ISO, ya que el uso de otros formatos a menudo causa errores debido a que la fecha no puede determinarse sin ambigüedades. Tenga en cuenta que la función ``format_date_field()`` es más rápida y más fiable. Los códigos de formato son: * ``d :`` el día como un número, sin cero inicial (de 1 a 31). * ``dd :`` el día como un número, con un cero inicial si es necesario (de 01 a 31). * ``ddd :`` el día de la semana abreviado según el idioma local (p. ej. de «lun» a «dom»). * ``dddd :`` el nombre local completo del día de la semana (p. ej. de «lunes» a «domingo»). * ``M :`` el mes como un número sin cero inicial (de 1 a 12). * ``MM :`` el mes como un número, con un cero inicial si es necesario (de 01 a 12). * ``MMM :`` el mes abreviado según el idioma local (p. ej. de «ene» a «dic»). * ``MMMM :`` el nombre local completo del mes (p. ej. de «enero» a «diciembre»). * ``yy :`` el año como un número de dos cifras (de 00 a 99). ­ * ``yyyy :`` el año como un número de cuatro cifras. * ``h :`` la hora sin cero inicial (de 0 a 11 o de 0 a 23, según am/pm). * ``hh :`` la hora con un cero inicial si es necesario (de 00 a 11 o de 00 a 23, según am/pm). * ``m :`` los minutos sin cero inicial (de 0 a 59). * ``mm :`` los minutos con un cero inicial si es necesaro (de 00 a 59). * ``s :`` los segundos sin cero inicial (de 0 a 59). * ``ss :`` los segundos con un cero inicial si es necesario (de 00 a 59). * ``ap :`` se escribe la hora en formato de 12 horas en lugar de 24, con «ap» sustituido por la forma local en minúsculas para am o pm. * ``AP :`` se escribe la hora en formato de 12 horas en lugar de 24, con «AP» sustituido por la forma local en mayúsculas para AM o PM. * ``aP :`` se escribe la hora en formato de 12 horas en lugar de 24, con «aP» sustituido por la forma local para am o pm. * ``Ap :`` se escribe la hora en formato de 12 horas en lugar de 24, con «Ap» sustituido por la forma local para AM o PM. * ``iso :`` la fecha con hora y zona horaria. Debe ser el único formato presente. * ``to_number :`` convierte la fecha y la hora a un número decimal (un «código de tiempo»). * ``from_number :`` convierte un número decimal (un «código de tiempo») a una fecha con formato ISO. Si desea un formato de fecha diferente, añada el texto de formato después de ``from_number`` y dos puntos (``:``). Ejemplo: :: format_date(valor, 'from_number:MMM dd yyyy') Puede arrojar resultados inesperados si la fecha a la que se está dando formato contiene meses en forma local, lo que puede ocurrir si se cambia el formato de fecha para que contenga ``MMMM``. El uso de ``format_date_field()`` evita este problema. .. _ff_format_date_field: format_date_field ^^^^^^^^^^^^^^^^^ .. class:: BuiltinFormatDateField ``format_date_field(nombre_campo, texto_formato)`` -- da formato al valor en el campo ``nombre_campo``, que debe ser el nombre de consulta de un campo de fecha, ya sea estándar o personalizado. Ver ``format_date()`` para los códigos de formato. Esta función es mucho más rápida que :ref:`format_date() ` y debe usarse cuando se esté dando formato al valor en un campo (columna). Es también más fiable porque opera directamente sobre la fecha. No puede usarse con fechas calculadas o variables de texto. Ejemplos: :: format_date_field('pubdate', 'yyyy.MM.dd') format_date_field('#date_read', 'MMM dd, yyyy') .. _ff_format_number: format_number ^^^^^^^^^^^^^ .. class:: BuiltinFormatNumber ``format_number(valor, plantilla)`` -- interpreta ``valor`` como un número y le da formato usando una plantilla de formato de Python como ``{0:5.2f}`` o ``{0:,d}`` o ``${0:5,.2f}``. La ``plantilla`` de formato debe empezar por ``{0:`` y terminar por ``}``, como en los ejemplos anteriores. Excepción: puede omitir el ``{0:`` inicial y el ``}`` final si la plantilla de formato contiene sólo un formato. Véase la documentación del `lenguaje de plantillas `_ y de `Python `_ para más ejemplos. Devuelve un texto vacío si el formato falla. .. _ff_human_readable: human_readable ^^^^^^^^^^^^^^ .. class:: BuiltinHumanReadable ``human_readable(valor)`` -- espera que ``valor`` sea un número y devuelve un texto que representa ese número en KB, MB, GB, etc. .. _ff_rating_to_stars: rating_to_stars ^^^^^^^^^^^^^^^ .. class:: BuiltinRatingToStars ``rating_to_stars(valor, usar_media_estrella)`` -- Devuelve ``valor`` como una serie de caracteres de estrella (``★``). ``valor`` debe ser un número entre ``0`` y ``5``. Ponga ``usar_media_estrella`` a ``1`` si quiere caracteres de media estrella para números fraccionarios, disponibles con columnas personalizadas de calificación. Funciones de URL ---------------------------------------------------------------- .. _ff_encode_for_url: encode_for_url ^^^^^^^^^^^^^^ .. class:: BuiltinEncodeForURL ``encode_for_url(valor, usar_más)`` -- devuelve el ``valor`` codificado para su use en un URL según se especifique con ``usar_más``. El valor se codifica primero para URL. Después, si ``usar_más`` es ``0`` los espacios se sustituyen por signos ``+`` (más). Si es ``1`` los espacios se sustituyen por ``%20`` Si no quiere codificar el ``valor`` pero quiere sustituir los espacios, use la función :ref:`re() `, como en ``re($series, ' ', '%20')``. Véanse también las funciones :ref:`make_url() `, :ref:`make_url_extended() ` y :ref:`query_string() `. .. _ff_make_url: make_url ^^^^^^^^ .. class:: BuiltinMakeUrl ``make_url(ruta, [nombre_de_consulta,valor_de_consulta]+)`` -- esta función es la manera más fácil de generar un URL de búsqueda. Usa una ``ruta``, la página web en la que quiere realizar la búsqueda, y pares ``nombre_de_consulta, valor_de_consulta`` con los que se construye la consulta. En general, el ``valor_de_consulta`` debe estar codificado para URL. Con esta función siempre se codifica y los espacios se sustituyen siempre por signos ``+``. Se debe proporcionar al menos un par ``nombre_de_consulta, valor de consulta`` Ejemplo: generar un URL de búsqueda en Wikipedia para el autor `Niccolò Machiavelli`: :: make_url('https://es.wikipedia.org/w/index.php', 'search', 'Niccolò Machiavelli') devuelve :: https://es.wikipedia.org/w/index.php?search=Niccol%C3%B2+Machiavelli Si está escribiendo una plantilla de URL para los detalles del libro de una columna personalizada, use ``$item_name`` o ``field('item_name')`` para obtener el valor del campo sobre el que se pulsó Ejemplo: si se pulsa sobre `Niccolò Machiavelli` puede generar el URL usando: :: make_url('https://es.wikipedia.org/w/index.php', 'search', $item_name) Véanse también las funciones :ref:`make_url_extended() `, :ref:`query_string() ` y :ref:`encode_for_url() ` .. _ff_make_url_extended: make_url_extended ^^^^^^^^^^^^^^^^^ .. class:: BuiltinMakeUrlExtended ``make_url_extended(...)`` -- this function is similar to :ref:`make_url() ` but gives you more control over the URL components. The components of a URL are **scheme**:://**authority**/**path**?\ **query string**. See `Uniform Resource Locator `_ on Wikipedia for more detail. The function has two variants: :: make_url_extended(scheme, authority, path, [query_name, query_value]+) and :: make_url_extended(scheme, authority, path, query_string) This function returns a URL constructed from the ``scheme``, ``authority``, ``path``, and either the ``query_string`` or a query string constructed from the query argument pairs. The ``authority`` can be empty, which is the case for ``calibre`` scheme URLs. You must supply either a ``query_string`` or at least one ``query_name, query_value`` pair. If you supply ``query_string`` and it is empty then the resulting URL will not have a query string section. Example 1: constructing a Wikipedia search URL for the author `Niccolò Machiavelli`: :: make_url_extended('https', 'en.wikipedia.org', '/w/index.php', 'search', 'Niccolò Machiavelli') returns :: https://en.wikipedia.org/w/index.php?search=Niccol%C3%B2+Machiavelli See the :ref:`query_string() ` function for an example using ``make_url_extended()`` with a ``query_string``. If you are writing a custom column book details URL template then use ``$item_name`` or ``field('item_name')`` to obtain the value of the field that was clicked on. Example: if `Niccolò Machiavelli` was clicked on then you can construct the URL using : :: make_url_extended('https', 'en.wikipedia.org', '/w/index.php', 'search', $item_name') See also the functions :ref:`make_url() `, :ref:`query_string() ` and :ref:`encode_for_url() `. **Se muestra la documentación en inglés debido al error de FFML:** Missing closing "`" for italics on line 36 in "make_url_extended" .. _ff_query_string: query_string ^^^^^^^^^^^^ .. class:: BuiltinQueryString ``query_string([nombre_de_consulta, valor_de_consulta, cómo_codificar]+)``-- devuelve un texto de consulta URL generado a partir de las ternas ``nombre_de_consulta, valor_de_consulta, cómo_codificar``. Un texto de consulta es una serie de elementos en la que cada elemento es de la forma ``nombre_de_consulta=valor_de_consulta`` y donde ``valor_de_consulta`` se codifica para URL como se indica. Los elementos de consulta están separados por caracteres ``&``. Si ``cómo_codificar`` es ``0``, ``valor_de_consulta`` se codifica y los espacios se sustituyen por signos ``+`` (más). Si ``cómo codificar`` es ``1``, ``valor_de_consulta`` se codifica con espacios sustituidos por ``%20``. Si ``cómo_codificar`` es ``2``, ``valor_de_consulta`` se devuelve sin cambios; no se codifica y no se sustituyen los espacios. Si no quiere codificar ``valor_de_consulta`` pero quiere sustituir los espacios, use la función :ref:`re() `, como en ``re($series, ' ', '%20')``. Use esta función si necesita un control específico sobre cómo se generan las distintas partes del texto de consulta. Puede entonces usar la consulta resultante en :ref:`make_url_extended() `, como en :: make_url_extended( 'https', 'servidor', 'ruta', query_string('encoded', 'Hendrik Bäßler', 0, 'unencoded', 'Hendrik Bäßler', 2)) giving you :: https://servidor/ruta?encoded=Hendrik+B%C3%A4%C3%9Fler&unencoded=Hendrik Bäßler Debe haber al menos una terna ``nombre_de_consulta, valor_de_consulta, cómo_codificar``, pero puede haber tantas como desee.. El valor devuelto es un texto de consulta URL con todos los elementos especificados, por ejemplo: ``nombre1=valor1[&nombreN=valorN]*``. Tenga en cuenta que el separador ``?`` entre `ruta` y `texto_de_consulta` no está incluido en el valor devuelto. Si está escribiendo una plantilla de URL para los detalles del libro de una columna personalizada, use ``$item_name`` o ``field('item_name')`` para obtener el valor del campo sobre el que se pulsó. También puede usar ``item_value_quoted``, donde el valor ya está codificado con signos más sustituyendo los espacios e ``item_value_no_plus``, done el valor ya está codificado con ``%20`` sustituyendo los espacios. Véanse también las funciones :ref:`make_url() `, :ref:`make_url_extended() ` y :ref:`encode_for_url() `. .. _ff_to_hex: to_hex ^^^^^^ .. class:: BuiltinToHex ``to_hex(valor)`` -- devuelve el texto ``valor`` codificado en hexadecimal. Esto es útil al construir URL de calibre. .. _ff_urls_from_identifiers: urls_from_identifiers ^^^^^^^^^^^^^^^^^^^^^ .. class:: BuiltinUrlsFromIdentifiers ``urls_from_identifiers(identificadores, ordenar_resultado)`` -- dada una lista de ``identificadores`` separados por comas, donde cada identificador es un par de valores separados por dos puntos (``nombre_id:valor_id``), devuelve una lista de URL HTML separados por comas, generados a partir de los identificadores. La lista no está ordenada si ``ordenar_resultado`` es ``0`` (carácter o número), en caso contrario se ordena alfabéticamente según el nombre del identificador. Los URL se generan de la misma manera que la columna predefinida de identificadores cuando se muestra en los detalles del libro. Funciones de base de datos -------------------------------------------------------------------------------------------------------- .. _ff_book_count: book_count ^^^^^^^^^^ .. class:: BuiltinBookCount ``book_count(consulta, usar_bv)`` -- devuelve el número de libros encontrados al buscar ``consulta``. Si ``usar_bv`` es ``0`` (cero), no se tienen en cuenta las bibliotecas virtuales. Esta función y su complemento ``book_values()`` son especialmente útiles en búsquedas de plantilla, permitiendo búsquedas que combinan la información de varios libros, como buscar series con un solo libro. No puede usarse en columnas compuestas, a no ser que que el ajuste ``allow_template_database_functions_in_composites`` sea True. Sólo puede usarse en la interfaz gráfica. Por ejemplo, esta búsqueda de plantilla usa esta función y su complemento para encontrar todas las series con un solo libro: * Definir una plantilla guardada (usando :guilabel:`Preferencias > Avanzado > Funciones de plantilla`) llamada ``series_un_solo_libro`` (el nombre es arbitrario). La plantilla es: :: program: 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, '') La primera vez que se ejecuta la plantilla (el primer libro que se comprueba) almacena los resultados de la búsqueda de la base de daos en una variable de plantilla global llamada ``vals``. Estos resultados se usan para comprobar los siguientes libros sin volver a realizar la búsqueda. * Usar la plantilla guardada en una búsqueda de plantilla: :: template:"program: series_un_solo_libro()#@#:n:1" Al usar una plantilla guardada en lugar de poner la plantilla en la búsqueda se eliminan los problemas causados por la necesidad de escapar las comillas en las expresiones de búsqueda. Esta función sólo puede usarse en la interfaz gráfica y en el servidor de contenidos. .. _ff_book_values: book_values ^^^^^^^^^^^ .. class:: BuiltinBookValues ``book_values(columna, consulta, sep, usar_bv)`` -- devuelve una lista de valores únicos contenidos en la columna ``columna`` (un nombre de consulta), separados por ``sep``, de los libros encontrados al buscar ``consulta``. Si ``usar_bv`` es ``0`` (cero), no se tienen en cuenta las bibliotecas virtuales. Esta función y su complemento ``book_count()`` son especialmente útiles en búsquedas de plantilla, permitiendo búsquedas que combinan la información de varios libros, como buscar series con un solo libro. No puede usarse en columnas compuestas, a no ser que que el ajuste ``allow_template_database_functions_in_composites`` sea True. Esta función sólo se puede usar en la interfaz gráfica y en el servidor de contenidos. .. _ff_extra_file_modtime: extra_file_modtime ^^^^^^^^^^^^^^^^^^ .. class:: BuiltinExtraFileModtime ``extra_file_modtime(nombre_archivo, texto_formato)`` -- devuelve la fecha (y hora) de modificación del archivo adicional ``nombre_archivo`` en la carpeta ``data/`` del libro si existe, o ``-1`` en caso contrario. El formato de la fecha se especifica en ``texto_formato`` (ver :ref:`format_date() ` para más detalles). Si ``texto_formato`` es un texto vacío, devuelve la fecha de modificación como un número real de segundos desde el inicio de la época. Ver también las funciones :ref:`has_extra_files() `, :ref:`extra_file_names() ` y :ref:`extra_file_size() `. El inicio de la época depende del sistema operativo. Esta función sólo puede usarse en la interfaz gráfica y en el servidor de contenidos. .. _ff_extra_file_names: extra_file_names ^^^^^^^^^^^^^^^^ .. class:: BuiltinExtraFileNames ``extra_file_names(sep [, patrón])`` -- devuelve una lista separada por ``sep`` de archivos adicionales en la carpeta ``data/`` del libro. Si el argumento opcional ``patrón`` (una expresión regular) está presente, la lista contiene sólo archivos que coinciden con ``patrón``. La coincidencia no distingue mayúsculas y minúsculas. Ver también las funciones :ref:`has_extra_files() `, :ref:`extra_file_modtime() ` y :ref:`extra_file_size() `. Esta función sólo puede usarse en la interfaz gráfica y en el servidor de contenidos. .. _ff_extra_file_size: extra_file_size ^^^^^^^^^^^^^^^ .. class:: BuiltinExtraFileSize ``extra_file_size(nombre_archivo)`` -- devuelve el tamaño en bytes del archivo adicional ``nombre_archivo`` en la carpeta ``data/`` del libro si existe, o ``-1`` en caso contrario. Ver también las funciones :ref:`has_extra_files() `, :ref:`extra_file_names() ` y :ref:`extra­_file_modtime() `. Esta función sólo puede usarse en la interfaz gráfica y en el servidor de contenidos. .. _ff_get_link: get_link ^^^^^^^^ .. class:: BuiltinGetLink ``get_link(nombre_campo, valor_campo)`` -- obtiene el enlace para el campo ``nombre_campo`` con el valor ``valor_campo``. Si no hay enlace asociado, devuelve un texto vacío. Ejemplos: * La siguiente plantilla devuelve el enlace asociado con la etiqueta «Ficción»: :: get_link('tags', 'Ficción') * Esta plantilla hace una lista de los enlaces para todas las etiquetas asociadas con un libro de la forma ``valor:enlace, ...``: :: 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 función sólo funciona en la interfaz gráfica y en el servidor de contenidos. .. _ff_get_note: get_note ^^^^^^^^ .. class:: BuiltinGetNote ``get_note(nombre_campo, valor_campo, texto)`` -- obtiene la nota para el campo ``nombre_campo`` con el valor ``valor_campo``. Si ``texto`` está vacío, devuelve el HTML de la nota, incluyendo imágenes. Si ``texto`` es ``1`` (o ``'1'``), devuelve el texto plano de la nota. Si la nota no existe, devuelve un texto vacío en ambos casos. Ejemplo: * Devuelve el HTML de la nota adjunta a la etiqueta «Ficción»: :: program: get_note('tags', 'Ficción', '') * Devuelve el texto plano de la nota adjunta al autor «Isaac Asimov»: :: program: get_note('authors', 'Isaac Asimov', 1) Esta función sólo funciona en la interfaz gráfica y en el servidor de contenidos. .. _ff_has_extra_files: has_extra_files ^^^^^^^^^^^^^^^ .. class:: BuiltinHasExtraFiles ``has_extra_files([patrón])`` devuelve el número de archivos adicionales o ``''`` (un texto vacío). Si el argumento opcional ``patrón`` (una expresión regular) está presente, sólo se cuentan archivos que coinciden con ``patrón``. La coincidencia no distingue mayúsculas y minúsculas. Ver también las funciones :ref:`extra_file_names() `, :ref:`extra_file_modtime() ` y :ref:`extra_file_size() `. Esta función sólo puede usarse en la interfaz gráfica y en el servidor de contenidos. .. _ff_has_note: has_note ^^^^^^^^ .. class:: BuiltinHasNote ``has_note(nombre_campo, valor_campo)``. Comprueba si el campo tiene una nota. Esta función tiene dos variantes: * Si ``valor_campo`` no es ``''`` (un texto vacío), devuelve ``'1'`` si el valor ``valor_campo`` en el campo ``nombre_campo`` tiene una nota adjunta, en caso contrario devuelve ``''``. Ejemplo: ``has_note('tags', 'Ficción')`` devuelve ``'1'`` si la etiqueta «Ficción» tiene una nota adjunta, en caso contrario devuelve ``''``. * Si ``valor_campo`` es ``''``, devuelve una lista de los valores de ``nombre_campo`` que tienen una nota. Si ningún elemento del campo tiene una nota, devuelve ``''``. Esta variante es útil para mostrar iconos de columna si algún valor del campo, y no un valor específico, tiene una nota. Ejemplo: ``has_note('authors', '')`` devuelve una lista de autores que tienen notas, o ``''`` si ninguno la tiene. También puede comprobar si todos los valores de ``nombre_campo`` tienen una nota comparando la longitud de la lista que devuelve esta función con la longitud de la lista de los valores de ``nombre_campo``. Ejemplo: :: list_count(has_note('authors', ''), '&') ==# list_count_field('authors') Esta función sólo funciona en la interfaz gráfica y en el servidor de contenidos. Funciones de fecha ------------------------------------------------------------------------ .. _ff_date_arithmetic: date_arithmetic ^^^^^^^^^^^^^^^ .. class:: BuiltinDateArithmetic ``date_arithmetic(valor, cálculo, fmt)`` -- calcula una nueva fecha a partir de ``valor`` usando ``cálculo``. Devuelve la nueva fecha con el formato opcional ``fmt``: si no se proporciona, el resultado estará en formato ISO. El argumento ``cálculo`` es un texto formado por pares ``vQ`` (``valorQué``) donde ``v`` es un número que puede ser negativo y ``Q`` es una de las letras siguientes: * ``s`` añade ``v`` segundos a ``fecha`` * ``m``: añade ``v`` minutos a ``fecha`` * ``h``: añade ``v`` horas a ``fecha`` * ``d``: añade ``v`` días a ``fecha`` * ``w``: añade ``v`` semanas a ``fecha`` * ``y``: añade ``v`` años a ``fecha``, donde un año son 365 días Ejemplo: ``'1s3d-1m'`` añade 1 segundo, añade 3 días y resta 1 minuto a ``fecha``. .. _ff_days_between: days_between ^^^^^^^^^^^^ .. class:: BuiltinDaysBetween ``days_between(fecha1, fecha2)`` -- devuelve el número de días entre ``fecha1`` y ``fecha2``. El número es positivo si ``fecha1`` es posterior a ``fecha2``, en caso contrario es negativo. Si ``fecha1`` o ``fecha2`` no son fechas, la función devuelve un texto vacío. .. _ff_today: today ^^^^^ .. class:: BuiltinToday ``today()`` -- devuelve un texto para la fecha y hora de hoy (ahora). Este valor está preparado para usarse con ``format_date()`` o ``days_between()``, pero puede manipularse como cualquier otro texto. La fecha está en formato `ISO `_. Iteración sobre valores -------------------------------------------------------------------------------------------- .. _ff_first_non_empty: first_non_empty ^^^^^^^^^^^^^^^ .. class:: BuiltinFirstNonEmpty ``first_non_empty(valor [, valor]*)`` -- devuelve el primer ``valor`` que no esté vacío. Si todos los valores están vacíos, se devuelve también un texto vacío. Puede incluir tantos valores como quiera. .. _ff_lookup: lookup ^^^^^^ .. class:: BuiltinLookup ``lookup(valor, [ patrón, clave, ]* clave_alternativa)`` -- Cada ``patrón`` se compara con ``valor`` en orden. Si un ``patrón`` coincide, se devuelve el valor del campo indicado por ``clave``. Si no coincide ningún patrón, se devuelve el valor del campo indicado por ``clave_alternativa``. Véase también la función :ref:`switch() `. .. _ff_switch: switch ^^^^^^ .. class:: BuiltinSwitch ``switch(valor, [patrónN, valorN,]+ otro_valor)`` -- para cada pareja ``patrónN, valorN``, comprueba si ``valor`` coincide con la expresión regular ``patrónN`` y, en tal caso, devuelve el ``valorN`` asociado. Si no coincide ningún ``patrónN``, devuelve ``otro_valor``. Pueden emplearse tantas parejas ``patrónN, valN`` como se desee. Se devuelve la primera coincidencia. .. _ff_switch_if: switch_if ^^^^^^^^^ .. class:: BuiltinSwitchIf ``switch_if([expresión_de prueba, expresión_de_valor,]+ otra_expresión)`` -- para cada par ``expresión_de_prueba, expresión_de_valor``, comprueba si ``expresión_de_prueba`` es True (no vacía) y, de ser así, devuelve el resultado de ``expresión_de_valor``. Si ninguna ``expresión_de_prueba`` es True, se devuelve el resultado de ``otra_expresión``. Puede haber tantos pares ``expresión_de_prueba, expresión_de_valor`` como se desee. Lógicas ---------------------------- .. _ff_and: and ^^^ .. class:: BuiltinAnd ``and(valor [, valor]*)`` -- devuelve el texto ``'1'`` si todos los valores son no vacíos, en caso contrario devuelve un texto vacío. Pueden usarse tantos valores como se desee. En la mayoría de los casos se puede usar el operador ``&&`` en lugar de esta función. Un motivo para no sustituir ``and()`` por ``&&`` es cuando la evaluación en cortocircuito puede cambiar el resultado debido a los efectos secundarios. Por ejemplo, ``and(a='',b=5)`` realizará las dos asignaciones, mientra que el operador ``&&`` no realizará la segunda. .. _ff_not: not ^^^ .. class:: BuiltinNot ``not(valor)`` -- devuelve el texto ``'1'`` si el valor está vacío, en caso contrario, devuelve un texto vacío. Esta función puede sustituirse a menudo por el operador de negación unario (``!``). .. _ff_or: or ^^ .. class:: BuiltinOr ``or(valor [, valor]*)`` -- devuelve el texto ``'1'`` si alguno de los valores no está vacío, en caso contrario, devuelve un texto vacío. Pueden incluirse tantos valores como se desee. Esta función puede sustituirse a menudo por el operador ``||``. Un motivo para no sustituirla es si la evaluación en cortocircuito puede cambiar los resultados debido a efectos secundarios. Manipulación de listas ---------------------------------------------------------------------------------------- .. _ff_list_count: list_count ^^^^^^^^^^ .. class:: BuiltinCount ``list_count(valor, separador)`` -- interpreta el valor como una lista de elementos separados por ``separador`` y devuelve el número de elementos de la lista. La mayoría de las listas usan una coma como separador, pero ``authors`` usa un carácter «&». Ejemplos: ``{tags:list_count(,)}``, ``{authors,list_count(&)}``. Sinónimos: ``count()``, ``list_count()`` .. _ff_list_count_field: list_count_field ^^^^^^^^^^^^^^^^ .. class:: BuiltinFieldListCount ``list_count_field(nombre_consulta)`` -- devuelve el número de elementos en el campo con el nombre de consulta ``nombre_consulta``. El campo debe tener varios valores, como ``authors`` o ``tags``, de lo contrario, la función genera un error. Esta función es mucho más rápida que ``list_count()`` porque opera directamente sobre los datos de calibre sin convertirlos primero a texto. Ejemplo: ``list_count_field('tags')``. .. _ff_list_count_matching: list_count_matching ^^^^^^^^^^^^^^^^^^^ .. class:: BuiltinListCountMatching ``list_count_matching(valor, patrón, separador)`` -- interpreta ``valor`` como una lista de elementos separados por ``separador`` y devuelve el número de elementos de la lista que coinciden con la expresión regular ``patrón``. Sinónimos: ``list_count_matching()``, ``count_matching()`` .. _ff_list_difference: list_difference ^^^^^^^^^^^^^^^ .. class:: BuiltinListDifference ``list_difference(lista1, lista2, separador)`` -- devuelve una lista construida eliminando de ``lista1`` cualquier elemento que aparezca en ``lista2``, sin distinguir mayúsculas y minúsculas. Los elementos de ``lista1`` y ``lista2`` están separados por ``separador``, así como los de la lista resultante. .. _ff_list_equals: list_equals ^^^^^^^^^^^ .. class:: BuiltinListEquals ``list_equals(lista1, sep1, lista2, sep2, val_sí, val_no)`` -- devuelve ``val_sí`` si ``lista1`` y ``lista2`` contienen los mismos elementos, en caso contrario devuelve ``val_no``. Los elementos se determinan dividiendo cada lista por el correspondiente carácter separador (``sep1`` o ``sep2``). El orden de los elementos no es relevante. La comparación no distingue mayúsculas y minúsculas. .. _ff_list_intersection: list_intersection ^^^^^^^^^^^^^^^^^ .. class:: BuiltinListIntersection ``list_intersection(lista1, lista2, separador)`` -- devuelve una lista construida eliminando de ``lista1`` cualquier elemento que no aparezca en ``lista2``, sin distinguir mayúsculas y minúsculas. Los elementos de ``lista1`` y ``lista2`` están separados por ``separador``, así como los de la lista resultante. .. _ff_list_join: list_join ^^^^^^^^^ .. class:: BuiltinListJoin ``list_join(con_separador, lista1, separador1 [, lista2, separador2]*)`` -- devuelve una lista formada por unión de los elementos en las listas de origen (``lista1``, etc.) usando ``con_separador`` entre los elementos de la lista resultante. Los elementos de cada lista de origen ``lista[123...]`` están separador por el correspondiente ``separador[123...]``. Una lista puede contener cero elementos. Puede ser un campo como ``publisher`` que contiene un solo valor, una lista de un elemento en la práctica. Los duplicados se eliminan sin distinción de mayúsculas y minúsculas. Los elementos se devuelven en el orden en que aparecen en las listas de origen. Si los elementos difieren sólo en mayúsculas y minúsculas, se usa la última aparición. Todos los separadores pueden ser de más de un carácter. Ejemplo: :: program: list_join('#@#', $authors, '&', $tags, ',') Puede usar ``list_join()`` sobre los resultados de ejecuciones previas de ``list_join()`` de la siguiente manera: :: program: a = list_join('#@#', $authors, '&', $tags, ','); b = list_join('#@#', a, '#@#', $#genre, ',', $#people, '&') Puede usar expresiones para generar una lista. Por ejemplo, supongamos que quiere los elementos de ``authors`` y ``#genre``, pero con estos últimos reemplazados por la palabra «Genre: » seguida de la primera letra del elemento, es decir con «Ficción» convertido en «Genre: F». Esto se consigue con lo siguiente: :: program: list_join('#@#', $authors, '&', list_re($#genre, ',', '^(.).*$', 'Genre: \1'), ',') .. _ff_list_re: list_re ^^^^^^^ .. class:: BuiltinListRe ``list_re(lista_orig, separador, incluir, sust_opc)`` -- construye una lista separando primero ``lista_orig`` en elementos usando el carácter ``separador``. Para cada elemento en la lista, comprueba si coincide con la expresión regular ``incluir``. Si coincide, se añade a la lista final. Si ``sust_opc`` no es un texto vacío, se aplica la sustitución antes de añadir el elemento a la lista final. .. _ff_list_re_group: list_re_group ^^^^^^^^^^^^^ .. class:: BuiltinListReGroup ``list_re_group(lista_orig, separador, incluir, búsqueda [, plantilla_grupo]*)`` -- como ``list_re()``, pero las sustituciones no son opcionales. Usa ``re_group(elemento, búsqueda, plantilla_grupo ...)`` para hacer sustituciones. .. _ff_list_remove_duplicates: list_remove_duplicates ^^^^^^^^^^^^^^^^^^^^^^ .. class:: BuiltinListRemoveDuplicates ``list_remove_duplicates(lista, separador)`` -- devuelve una lista construida por eliminación de los duplicados en ``lista``. No distingue mayúsculas y minúsculas, se mantiene la última versión. Los elementos de ``lista`` están separados por ``separador``, así como los de la lista resultante. .. _ff_list_sort: list_sort ^^^^^^^^^ .. class:: BuiltinListSort ``list_sort(valor, dirección, separador)`` -- devuelve la lista ``valor`` ordenada lexicográficamente sin distinción de mayúsculas y minúsculas. Si ``dirección`` es cero (número o carácter), la lista se ordena de manera ascendente, en caso contrario, de manera descendente. Los elementos de ``valor`` están separados por ``separador``, así como los de la lista resultante. .. _ff_list_split: list_split ^^^^^^^^^^ .. class:: BuiltinListSplit ``list_split(lista, sep, prefijo_id)`` -- divide la lista``lista`` en valores separados por ``sep`` y asigna los valores a variables con nombre ``prefijo_id_N``, donde N es la posición del valor en la lista. El primer elemento tiene posición 0 (cero). La función devuelve el último elemento de la lista. Ejemplo: :: list_split('uno:dos:bla', ':', 'var') es equivalente a: :: var_0 = 'uno'; var_1 = 'dos'; var_2 = 'bla' .. _ff_list_union: list_union ^^^^^^^^^^ .. class:: BuiltinListUnion ``list_union(lista1, lista2, separador)`` -- devuelve una lista construida por combinación de los elementos en ``lista1`` y ``lista2``, eliminando los duplicados de ``lista2`` (no distingue mayúsculas y minúsculas, se mantiene la versión de ``lista1``). Los elementos de ``lista1`` y ``lista2`` están separados por ``separador``, así como los de la lista resultante. Sinónimos: ``merge_list()``, ``list_union()`` .. _ff_range: range ^^^^^ .. class:: BuiltinRange ``range(inicio, fin, paso, límite)`` -- devuelve una lista de números generados por iteración en el intervalo especificado por los argumentos ``inicio``, ``fin`` y ``paso``, con una longitud máxima de ``límite``. El primer elemento generado es ``inicio``. Los valores siguientes son ``valor_sig = valor_act + paso``. El proceso continúa mientras ``valor_sig < fin``, suponiendo que ``paso`` sea positivo, en caso contrario mientras ``valor_sig > fin``. Si ``inicio`` no cumple la condición, es decir si ``inicio >= fin`` (en caso de que ``paso`` sea positivo), se devuelve una lista vacía. El ``límite`` establece la longitud máxima de la lista y tiene un valor predeterminado de 1000. Los argumentos ``inicio``, ``paso`` y ``límite`` son opcionales. Si se ejecuta ``range()`` con un argumento, se interpreta como ``fin``. Dos argumentos especifican ``inicio`` y ``fin``. Tres argumentos especifican ``inicio``, ``fin`` y ``paso``. Cuatro argumentos especifican ``inicio``, ``fin``, ``paso`` y ``límite``. Ejemplos: :: 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) -> error(límite superado). .. _ff_subitems: subitems ^^^^^^^^ .. class:: BuiltinSubitems ``subitems(valor, índice_inicio, índice_fin)`` -- Esta función separa listas de elementos jerárquicos de tipo etiqueta, tales como los géneros. Interpreta ``valor`` como una lista de elementos separados por comas, donde cada elemento es a su vez una lista de elementos separados por puntos. Devuelve una nueva lista formada tomando de cada elemento los componentes entre las posiciones ``índice_inicio`` e ``índice_fin`` y combinando los resultados. Se eliminan los duplicados. El primer subelemento de cada lista separada por puntos ocupa la posición cero. Si un índice es negativo, se cuenta desde el final de la lista. Como caso especial, si ``índice_fin`` es cero, se considera que es el final de la lista. Ejemplos: * Suponiendo que la columna #genero contiene «A.B.C»: * ``{#genero:subitems(0,1)}`` devuelve «A» * ``{#genero:subitems(0,2)}`` devuelve «A.B» * ``{#genero:subitems(1,0)}`` devuelve «B.C» * Suponiendo que la columna #genero contiene «A.B.C, D.E»: * ``{#genero:subitems(0,1)}`` devuelve «A, D» * ``{#genero:subitems(0,2)}`` devuelve «A.B, D.E» .. _ff_sublist: sublist ^^^^^^^ .. class:: BuiltinSublist ``sublist(valor, índice_inicio, índice_fin, separador)`` -- interpreta ``valor`` como una lista de elementos separados por ``separador`` y devuelve una nueva lista con los elementos comprendidos entre la posición ``índice_inicio`` e ``índice_fin``. El primer elemento ocupa la posición cero. Si un índice es negativo, se cuenta desde el final de la lista. Como caso especial, si ``índice_fin`` es cero, se considera que es el final de la lista. Ejemplos suponiendo que la columna de etiquetas (definida como valores separados por comas) contiene «A, B, C»: * ``{tags:sublist(0,1,\,)}`` devuelve «A» * ``{tags:sublist(-1,0,\,)}`` devuelve «C» * ``{tags:sublist(0,-1,\,)}`` devuelve «A, B» Manipulación de textos ---------------------------------------------------------------------------------------- .. _ff_character: character ^^^^^^^^^ .. class:: BuiltinCharacter ``character(nombre_carácter)`` -- devuelve el carácter con nombre ``nombre_carácter``. Por ejemplo, ``character('newline')`` devuelve un carácter de salto de línea (``'\n'``'). Los nombres de carácter admitidos son ``newline`` (salto de línea), ``return`` (retorno de carro), ``tab`` (tabulación) y ``backslash`` (barra invertida). .. _ff_check_yes_no: check_yes_no ^^^^^^^^^^^^ .. class:: BuiltinCheckYesNo ``check_yes_no(nombre_de_campo, no_definido, es_false, es_true)`` -- comprueba si el valor del campo de tipo sí o no identificado por el nombre de consulta ``nombre_de campo`` coincide con el valor especificado en los parámetros. Devuelve ``'Yes'`` si coincide, y un texto vació en caso contrario. Establezca el parámetro ``no_definido``, ``es_false`` o ``es_true`` a 1 (el número) para comprobar dicha condición, en caso contrario establézcalos a 0. Ejemplo: ``check_yes_no("#bool", 1, 0, 1)`` devuelve ``'Yes'`` si el campo de tipo sí o no ``#bool`` es True o no está definido (no es ni True ni False). Más de uno de ``no_definido``, ``es_false`` y ``es_true`` puede ser 1. Esta función sólo funciona en la interfaz gráfica y en el servidor de contenidos. .. _ff_contains: contains ^^^^^^^^ .. class:: BuiltinContains ``contains(valor, patrón, texto_si_coincide, texto_si_no_coincide)`` -- comprueba si ``valor`` coincide con la expresión regular ``patrón``. Devuelve ``texto_si_coincide`` si el patrón coincide con el valor, en caso contrario devuelve ``texto_si_no_coincide``. .. _ff_field_exists: field_exists ^^^^^^^^^^^^ .. class:: BuiltinFieldExists ``field_exists(nombre_consulta)`` -- comprueba si existe un campo (columna) con el nombre de consulta ``nombre_consulta``, devuelve ``'1'`` si es así y un texto vacío si no. .. _ff_ifempty: ifempty ^^^^^^^ .. class:: BuiltinIfempty ``ifempty(valor, texto_si_vacío)`` -- si ``valor`` no está vacío, devuelve dicho ``valor``, en caso contrario devuelve ``texto_si_vacío``. .. _ff_re: re ^^ .. class:: BuiltinRe ``re(valor, patrón, sustitución)`` -- devuelve ``valor`` después de aplicar la expresión regular. Todas las veces que aparezca ``patrón`` en el valor se sustituirá por ``sustitución``. El lenguaje de plantillas usa `expresiones regulares de Python `_, sin distinguir mayúsculas y minúsculas. .. _ff_re_group: re_group ^^^^^^^^ .. class:: BuiltinReGroup ``re_group(valor, patrón [, plantilla_para_grupo]*)`` -- devuelve un texto formado por aplicación de la expresión regular ``patrón`` a ``valor``, sustituyendo cada coincidencia con el texto devuelto por la correspondiente plantilla. En el `modo de programación de plantillas `_, como en las funciones ``template`` y ``eval``, debe usarse ``[[`` en lugar de ``{`` y ``]]`` en lugar de ``}``. El siguiente ejemplo busca un nombre de serie con más de una palabra y pone la primera palabra en mayúsculas: :: program: re_group(field('series'), "(\S* )(.*)", "{$:uppercase()}", "{$}")'} .. _ff_shorten: shorten ^^^^^^^ .. class:: BuiltinShorten ``shorten(valor, car_izq, texto_medio, car_der)`` -- devuelve una versión abreviada ``valor``, consistente en un número ``car_izq`` de caracteres del principio de ``valor``, seguidos de ``texto_medio``, seguido de un número ``car_der`` de caracteres del final de ``valor``. ``car_izq`` y ``car_der`` deben ser números enteros no negativos. Ejemplo, supongamos que quiere mostrar el título con una longitud máxima de 15 caracteres. Una plantilla que hace esto es ``{title:shorten(9,-,5)}``. Para un libro con el título `Novísima recopilación de las leyes de España` el resultado será `Novísima -spaña`: los primeros 9 caracteres del título, un ``-`` y los últimos 5 caracteres. Si la longitud del valor es menor que ``car_izq`` + ``car_der`` + la longitud de ``texto_medio``, se usará el valor intacto. Por ejemplo, el título `La colmena` no se cambiará. .. _ff_strcat: strcat ^^^^^^ .. class:: BuiltinStrcat ``strcat(a [, b]*)`` -- devuelve un texto formado por concatenación de todos los argumentos. Puede tomar cualquier número de argumentos. En la mayoría de los casos puede usarse el operador ``&`` en lugar de esta función. .. _ff_strcat_max: strcat_max ^^^^^^^^^^ .. class:: BuiltinStrcatMax ``strcat_max(máx, texto1 [, prefijo2, texto2]*)`` -- devuelve un texto formado por concatenación de los argumentos. El valor devuelto es inicialmente ``texto1``. Se van añadiendo textos formados por parejas ``prefijo``, ``texto`` al final del valor mientras la longitud del resultado sea menor que ``máx``. Los prefijos pueden estar vacíos. El resultado es siempre al menos ``texto1``, aunque su longitud sea mayor que ``máx``. Pueden especificarse tantas parejas ``prefijo``, ``texto`` como se desee. .. _ff_strlen: strlen ^^^^^^ .. class:: BuiltinStrlen ``strlen(valor)`` -- Devuelve la longitud del texto ``valor``. .. _ff_substr: substr ^^^^^^ .. class:: BuiltinSubstr ``substr(valor, inicio, fin)`` -- devuelve los caracteres entre la posición ``inicio`` y ``fin`` de ``valor``. El primer carácter de ``valor`` está en la posición cero. Si ``fin`` es negativo, entonces indica la posición contando desde la derecha. Si ``fin`` es cero, indica el último carácter. Por ejemplo, ``substr('12345', 1, 0)`` devuelve ``'2345'``, y ``substr('12345', 1, -1)`` devuelve ``'234'``. .. _ff_swap_around_articles: swap_around_articles ^^^^^^^^^^^^^^^^^^^^ .. class:: BuiltinSwapAroundArticles ``swap_around_articles(valor, separador)`` -- devuelve ``valor`` con los artículos puestos al final, separados por punto y coma. ``valor`` puede ser una lista, en cuyo caso se procesará cada elemento de la lista. Si ``valor`` es una lista, debe proporcionar el ``separador`` de los elementos de la lista. Si no se proporciona ningún ``separador`` o si es un texto vacío, ``valor`` se trata como un único valor, no una lista. Los «artículos» son los que calibre usa para generar el orden de título. .. _ff_swap_around_comma: swap_around_comma ^^^^^^^^^^^^^^^^^ .. class:: BuiltinSwapAroundComma ``swap_around_comma(valor)`` -- dado un ``valor`` de la forma ``B, A``, devuelve ``A B``. Esto es útil para convertir nombres en formato APELLIDO, NOMBRE a NOMBRE APELLIDO. Si no hay ninguna coma en ``valor``, la función devuelve ``valor`` sin cambios. .. _ff_test: test ^^^^ .. class:: BuiltinTest ``test(valor, texto_si_no_vacío, texto_si_vacío)`` -- devuelve ``texto_si_no_vacío`` si ``valor`` no está vacío, devuelve ``texto_si_vacío`` en caso contrario. .. _ff_transliterate: transliterate ^^^^^^^^^^^^^ .. class:: BuiltinTransliterate ``transliterate(valor)`` -- Devuelve un texto en el alfabeto latino formado por aproximación del sonido de las palabras en ``valor``. Por ejemplo, si ``valor`` es ``Фёдор Миха́йлович Достоевский`` la función devuelve ``Fiodor Mikhailovich Dostoievskii``. Obtención de valores de metadatos ------------------------------------------------------------------------------------------------------------------------------------ .. _ff_annotation_count: annotation_count ^^^^^^^^^^^^^^^^ .. class:: BuiltinAnnotationCount ``annotation_count()`` -- devuelve el número total de anotaciones de todos los tipos en el libro actual. Esta función sólo funciona en la interfaz gráfica y en el servidor de contenidos. .. _ff_approximate_formats: approximate_formats ^^^^^^^^^^^^^^^^^^^ .. class:: BuiltinApproximateFormats ``approximate_formats()`` -- devuelve una lista separada por comas de formatos que en algún momento estuvieron asociados con el libro. Dado que la lista viene de la base de datos de calibre y no del sistema de archivos, no hay garantía de que esta lista sea correcta, aunque probablemente lo sea. Tenga en cuenta que los nombres de formato están siempre en mayúsculas, como en «EPUB». La funcion``approximate_formats()`` es mucho más rápida que las funciones ``formats_...``. Esta función funciona sólo en la interfaz gráfica. Si quiere usar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, debe crear una columna personalizada de tipo «Columna generada a partir de otras columnas», usar la función en la plantilla de dicha columna y usar el valor de la columna en las plantillas para guardar o enviar. .. _ff_author_links: author_links ^^^^^^^^^^^^ .. class:: BuiltinAuthorLinks ``author_links(sep_val, sep_par)`` -- devuelve un texto que contiene una lista de autores y enlaces de autores de la forma: ``autor1 sep_val enlace_autor1 sep_par autor2 sep_val enlace_autor2`` etc. Cada autor está separado de su correspondiente enlace por el texto ``sep_val``, sin espacios adicionales. Suponiendo que ``sep_val`` sea ``:``, los pares ``autor:enlace_autor`` están separados por el texto ``sep_par``, sin espacios adicionales. Es responsabilidad del usuario proporcionar separadores que no aparezcan en los nombres o enlaces de autor. El nombre de autor se incluye aunque su enlace esté vacío. .. _ff_author_sorts: author_sorts ^^^^^^^^^^^^ .. class:: BuiltinAuthorSorts ``author_sorts(separador)`` -- devuelve un texto que contiene la lista de valores de orden de autor para los autores del libro. El orden de autor es el que figura en los metadatos de información autores (diferente del valor de orden de autor del libro). La lista devuelta es de la forma ``orden_de_autor_1`` ``separador`` ``orden_de_autor_2``, etc. Los valores de orden de autor en la lista están en el mismo orden que los autores del libro. Si quiere espacios alrededor de ``separador``, inclúyalos en el valor de ``separador``. .. _ff_booksize: booksize ^^^^^^^^ .. class:: BuiltinBooksize ``booksize()`` -- devuelve el valor del campo de calibre ``size`` (tamaño). Devuelve ``''`` si el libro no tiene formatos. Esta función funciona sólo en la interfaz gráfica. Si quiere usar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, debe crear una columna personalizada de tipo «Columna generada a partir de otras columnas», usar la función en la plantilla de dicha columna y usar el valor de la columna en las plantillas para guardar o enviar .. _ff_connected_device_name: connected_device_name ^^^^^^^^^^^^^^^^^^^^^ .. class:: BuiltinConnectedDeviceName ``connected_device_name(ubicación_de_almacenamiento)`` -- si hay un dispositivo conectado, devuelve el nombre del dispositivo, en caso contrario devuelve un texto vacío. Cada ubicación de almacenamiento de un dispositivo tiene un nombre diferente. Los nombres de ``ubicación_de_almacenamiento`` son ``'main'``, ``'carda'`` y ``'cardb'``. Esta función sólo está disponible en la interfaz gráfica. .. _ff_connected_device_uuid: connected_device_uuid ^^^^^^^^^^^^^^^^^^^^^ .. class:: BuiltinConnectedDeviceUUID ``connected_device_uuid(ubicación_de_almacenamiento)`` -- si un dispositivo está conectado, entonces devuelve el uuid (identificador único) del dispositivo, de lo contrario devuelve un texto vacío. Cada ubicación de almacenamiento de un dispositivo tiene un uuid diferente. Los nombres de ``ubicación_de_almacenamiento`` son ``'main'``, ``'carda'`` y ``'cardb'``. Esta función sólo está disponible en la interfaz gráfica. .. _ff_current_library_name: current_library_name ^^^^^^^^^^^^^^^^^^^^ .. class:: BuiltinCurrentLibraryName ``current_library_name()`` -- devuelve la última parte de la ruta a la biblioteca de calibre actual. .. _ff_current_library_path: current_library_path ^^^^^^^^^^^^^^^^^^^^ .. class:: BuiltinCurrentLibraryPath ``current_library_path()`` -- devuelve la ruta completa a la biblioteca de calibre actual. .. _ff_current_virtual_library_name: current_virtual_library_name ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. class:: BuiltinCurrentVirtualLibraryName ``current_virtual_library_name()`` -- devuelve el nombre de la biblioteca virtual actual si hay alguna, en caso contrario devuelve un texto vacío. Se conservan mayúsculas y minúsculas. Ejemplo: :: program: current_virtual_library_name()`` Esta función sólo funciona en la interfaz gráfica. .. _ff_field: field ^^^^^ .. class:: BuiltinField ``field(nombre_de_consulta)`` -- devuelve el campo de metadatos identificado por ``nombre_de_consulta``. Puede usarse el prefijo ``$`` en lugar de la función, como en ``$tags``. .. _ff_formats_modtimes: formats_modtimes ^^^^^^^^^^^^^^^^ .. class:: BuiltinFormatsModtimes ``formats_modtimes(formato_fecha)`` -- devuelve una lista separada por comas de elementos separados por dos puntos (``FMT:FECHA``) que contienan las fechas de modificación para los formatos de un libro. El argumento ``formato_fecha`` especifica cómo se da formato a la fecha. Véase la función :ref:`format_date() ` para más detalles. Puede usar la función :ref:`select() ` para obtener la fecha de modificación de un formato específico. Tenga en cuenta que los nombres de formato siempre están en mayúsculas, como en «EPUB». .. _ff_formats_paths: formats_paths ^^^^^^^^^^^^^ .. class:: BuiltinFormatsPaths ``formats_paths()`` -- devuelve una lista separada por comas de elementos separados por dos puntos (``FMT:RUTA``) que contienen la ruta completa a los formatos de un libro. Puede usar la función ``select()`` para obtener la ruta a un formato específico. Tenga en cuenta que los nombres de formato están siempre en mayúsculas, como en «EPUB». .. _ff_formats_sizes: formats_sizes ^^^^^^^^^^^^^ .. class:: BuiltinFormatsSizes ``formats_sizes()`` -- devuelve una lista separada por comas de elementos separados por dos puntos (``FMT:TAMAÑO``) que contienen los tamaños en bytes de los formatos de un libro. Puede usar la función ``select()`` para obtener el tamaño de un formato específico. Tenga en cuenta que los nombres de formato siempre están en mayúsculas, como en «EPUB». .. _ff_has_cover: has_cover ^^^^^^^^^ .. class:: BuiltinHasCover ``has_cover()`` -- devuelve ``'Yes'`` si el libro tiene portada, en caso contrario devuelve un texto vacío. .. _ff_is_marked: is_marked ^^^^^^^^^ .. class:: BuiltinIsMarked ``is_marked()`` -- comprueba si el libro está «marcado» en calibre. Si lo está, devuelve el valor de la marca, bien ``'true'`` (en minúsculas) o bien una lista separada por comas de los nombres de marca. Devuelve ``''`` (un texto vacío) si el libro no está marcado. Esta función sólo está disponible en la interfaz gráfica. .. _ff_language_codes: language_codes ^^^^^^^^^^^^^^ .. class:: BuiltinLanguageCodes ``language_codes(nombres)`` -- devuelve los `códigos de idioma `_ correspondientes a los nombres de idioma en ``nombres``. Los nombres deben estar en el idioma actual. El argumento ``nombres`` es una lista separada por comas. .. _ff_language_strings: language_strings ^^^^^^^^^^^^^^^^ .. class:: BuiltinLanguageStrings ``language_strings(valor, localizar)`` -- devuelve los nombres de los idiomas identificados por los códigos de idioma (`ver aquí los nombres y códigos `_) pasados como ``valor``. Ejemplo: ``{languages:language_strings()}``. Si ``localizar`` es cero, devuelve los nombres en inglés. Si ``localizar`` no es cero, devuelve los nombres en el idioma actual. El argumento ``códigos_idioma`` es una lista separada por comas. .. _ff_ondevice: ondevice ^^^^^^^^ .. class:: BuiltinOndevice ``ondevice()`` -- devuelve el texto ``'Yes'`` si ``ondevice`` está activado, si no, devuelve un texto vacío. Esta función funciona sólo en la interfaz gráfica. Si quiere usar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, debe crear una columna personalizada de tipo «Columna generada a partir de otras columnas», usar la función en la plantilla de dicha columna y usar el valor de la columna en las plantillas para guardar o enviar. .. _ff_raw_field: raw_field ^^^^^^^^^ .. class:: BuiltinRawField ``raw_field(nombre_de_consulta [, predeterminado_opcional])`` -- devuelve el campo de metadatos nombrado por ``nombre_de_consulta`` sin aplicar ningún formato. Evalúa y devuelve el segundo argumento opcional ``predeterminado_opcional`` si el campo no está definido (``None``). Puede usarse el prefijo ``$$`` en lugar de la función, como en ``$$pubdate``. .. _ff_raw_list: raw_list ^^^^^^^^ .. class:: BuiltinRawList ``raw_list(nombre_de_consulta, separador)`` -- devuelve la lista de metadatos nombrada por ``nombre_de_consulta`` sin aplicar ningún formato ni ordenación, con los elementos separados por ``separador``. .. _ff_series_sort: series_sort ^^^^^^^^^^^ .. class:: BuiltinSeriesSort ``series_sort()`` -- devuelve el valor de orden de serie. .. _ff_user_categories: user_categories ^^^^^^^^^^^^^^^ .. class:: BuiltinUserCategories ``user_categories()`` -- devuelve una lista separada por comas de las categorías de usuario que contiene este libro. Esta función sólo funciona en la interfaz gráfica. Si desea utilizar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, deberá crear una plantilla personalizada «Columna generada a partir de otras columnas», utilice la función en la plantilla de esa columna y use el valor de esa columna en las plantillas para guardar o enviar. .. _ff_virtual_libraries: virtual_libraries ^^^^^^^^^^^^^^^^^ .. class:: BuiltinVirtualLibraries ``virtual_libraries()`` -- devuelve una lista separada por comas de bibliotecas virtuales que contienen este libro. Esta función funciona sólo en la interfaz gráfica. Si quiere usar estos valores en las plantillas para guardar en el disco o enviar al dispositivo, debe crear una columna personalizada de tipo «Columna generada a partir de otras columnas», usar la función en la plantilla de dicha columna y usar el valor de la columna en las plantillas para guardar o enviar. Esta función sólo funciona en la interfaz gráfica. Otros -------------------- .. _ff_arguments: arguments ^^^^^^^^^ .. class:: BuiltinArguments ``arguments(id[=expresión] [, id[=expresión]]*)`` -- usada en una plantilla guardada para obtener el valor de los argumentos pasados en la invocación. Esta función declara e inicializa las variables locales con los nombres suministrados (los ``id``), parámetros en la práctica. Las variables son posicionales: obtienen el valor del argumento usado en la misma posición en la invocación. Si el argumento correspondiente no aparece en la invocación, ``arguments()`` asigna a esa variable el valor predeterminado suministrado. Si no hay valor predeterminado, será un texto vacío. .. _ff_assign: assign ^^^^^^ .. class:: BuiltinAssign ``assign(id, valor)`` -- asigna ``valor`` a ``id`` y devuelve ``valor``. ``id`` debe ser un identificador, no una expresión. En la mayoría de los casos puede usarse el operador ``=`` en lugar de esta función. .. _ff_globals: globals ^^^^^^^ .. class:: BuiltinGlobals ``globals(id[=expresión] [, id[=expressión]]*)`` -- Obtiene «variables globales» que pueden pasarse al formateador. El nombre ``id`` es el nombre de la variable global. Esta función declara e inicializa variables locales con los nombres de las variables globales que se le pasan. Si la variable correspondiente no está presente en las variables globales creadas, asignará a dicha variable el valor predeterminado suministrado. Si no hay valor predeterminado, se asigna a la variable el texto vacío. .. _ff_is_dark_mode: is_dark_mode ^^^^^^^^^^^^ .. class:: BuiltinIsDarkMode ``is_dark_mode()`` - devuelve ``'1'`` si calibre se ejecuta en modo oscuro, ``''`` (un texto vacío) en caso contrario. Esta función se puede utilizar en reglas avanzadas de color e iconos para elegir diferentes colores colores o iconos según el modo. Ejemplo: :: if is_dark_mode() then 'dark.png' else 'light.png' fi .. _ff_print: print ^^^^^ .. class:: BuiltinPrint ``print(a [, b]*)`` -- escribe los argumentos en la salida estándar. Sólo será visible si inicia calibre a partir de línea de órdenes (``calibre-debug -g``). La función ``print`` siempre devuelve su primer argumento. .. _ff_set_globals: set_globals ^^^^^^^^^^^ .. class:: BuiltinSetGlobals ``set_globals(id[=expresión] [, id[=expresión]]*)`` -- Establece las «variables globales» que se pueden pasar al formateador. Las variables globales toman el nombre del ``id`` indicado. Se usa el valor del ``id`` a no ser que se suministre una expresión. Recursivas ---------------------------------------- .. _ff_eval: eval ^^^^ .. class:: BuiltinEval ``eval(texto)`` -- evalúa ``texto`` como un programa, pasando las variables locales. Esto permite usar el procesador de plantillas para elaborar resultados complejos a partir de variables locales. En el `modo de programación de plantillas `_, dado que los caracteres ``{`` y ``}`` se interpretan antes de evaluar la plantilla, debe usarse ``[[`` en lugar de ``{`` y ``]]`` para ``}``. Se convertirán automáticamente. Tenga en cuenta que los prefijos y sufijos (la sintaxis ``|prefijo|sufijo``) no pueden usarse en el argumento de esta función en el modo de programación de plantillas. .. _ff_template: template ^^^^^^^^ .. class:: BuiltinTemplate ``template(x)`` -- evalúa ``x`` como una plantilla. La evaluación se realiza en un contexto propio, lo que significa que las variables no se comparten entre el proceso que llama a la función y la evaluación de la plantilla. Si no se usa el modo de programación general, dado que los caracteres ``{`` y ``}`` tienen un uso especial, debe usar ``[[`` en lugar de ``{`` y ``]]`` para ``}``; se convertirán automáticamente. Por ejemplo, ``template(\'[[title_sort]]\')`` evaluará la plantilla ``{title_sort}`` y devolverá su valor. Tenga en cuenta que los prefijos y sufijos (la sintaxis ``|prefijo|sufijo``) no pueden usarse en el argumento de esta función en el modo de programación de plantillas. Relacionales ------------------------------------------------ .. _ff_cmp: cmp ^^^ .. class:: BuiltinCmp ``cmp(valor, y, mn, ig, my)`` -- compara ``valor`` e ``y`` después de convertirlas en números. Devuelve ``mn`` si ``valor <# y``, ``ig`` si ``valor ==# y`` y ``my`` en caso contrario. Esta función puede sustituirse normalmente por uno de los operadores de comparación numérica (``==#``, ``<#``, ``>#``, etc.). .. _ff_first_matching_cmp: first_matching_cmp ^^^^^^^^^^^^^^^^^^ .. class:: BuiltinFirstMatchingCmp ``first_matching_cmp(val, [ cmp, resultado, ]* otro_resultado)`` -- compara ``val < cmp`` consecutivamente y devuelve el ``resultado`` asociado para la primera comparación que sea cierta. Devuelve ``otro_resultado`` si ninguna comparación es cierta. Ejemplo: :: i = 10; first_matching_cmp(i,5,"pequeño",10,"mediano",15,"grande","enorme") devuelve ``"grande"``. El mismo ejemplo con un primer valor de 16 devuelve ``"enorme"``. .. _ff_strcmp: strcmp ^^^^^^ .. class:: BuiltinStrcmp ``strcmp(x, y, mn, ig, my)`` -- hace una comparación lexicográfica sin distinción de mayúsculas y minúsculas entre ``x`` e ``y`` como textos. Devuelve ``mn`` si ``x < y``, ``ig`` si ``x == y``, ``my`` en otros casos. Esta función puede sustituirse a menudo por los operadores de comparación lexicográfica (``==``, ``>``, ``<``, etc.) .. _ff_strcmpcase: strcmpcase ^^^^^^^^^^ .. class:: BuiltinStrcmpcase ``strcmpcase(x, y, mn, ig, my)`` -- hace una comparación con distinción de mayúsculas y minúsculas entre ``x`` e ``y``. Devuelve ``mn`` si ``x < y``. Devuelve ``ig`` si ``x = y``, o ``my`` en caso contrario. Atención: Éste NO es el comportamiento predeterminado usado por calibre, por ejemplo, en los operadores de comparación léxica (``==``, ``>``, ``<``, etc.). Esta función podría dar resultados inesperados, use preferentemente ``strcmp()`` siempre que sea posible. 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. .. module:: calibre.ebooks.metadata.book.base .. autoclass:: Metadata :members: :member-order: bysource .. data:: STANDARD_METADATA_FIELDS The set of standard metadata fields. .. literalinclude:: ../../../src/calibre/ebooks/metadata/book/__init__.py :lines: 7-