.. _templaterefcalibre-ms:

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

Arithmetic
----------

add(x, y)
^^^^^^^^^

.. autoclass:: BuiltinAdd

ceiling(x)
^^^^^^^^^^

.. autoclass:: BuiltinCeiling

divide(x, y)
^^^^^^^^^^^^

.. autoclass:: BuiltinDivide

floor(x)
^^^^^^^^

.. autoclass:: BuiltinFloor

fractional_part(x)
^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinFractionalPart

mod(x)
^^^^^^

.. autoclass:: BuiltinMod

multiply(x, y)
^^^^^^^^^^^^^^

.. autoclass:: BuiltinMultiply

round(x)
^^^^^^^^

.. autoclass:: BuiltinRound

subtract(x, y)
^^^^^^^^^^^^^^

.. autoclass:: BuiltinSubtract

Boolean
-------

and(value, value, ...)
^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinAnd

not(value)
^^^^^^^^^^

.. autoclass:: BuiltinNot

or(value, value, ...)
^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinOr

Date functions
--------------

days_between(date1, date2)
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinDaysBetween

today()
^^^^^^^

.. autoclass:: BuiltinToday

Formatting values
-----------------

finish_formatting(val, fmt, prefix, suffix)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinFinishFormatting

format_date(val, format_string)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinFormatDate

format_number(v, template)
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinFormatNumber

human_readable(v)
^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinHumanReadable

rating_to_stars(value, use_half_stars)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinRatingToStars

Get values from metadata
------------------------

annotation_count()
^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinAnnotationCount

approximate_formats()
^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinApproximateFormats

author_links(val_separator, pair_separator)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinAuthorLinks

author_sorts(val_separator)
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinAuthorSorts

booksize()
^^^^^^^^^^

.. autoclass:: BuiltinBooksize

connected_device_name(storage_location)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinConnectedDeviceName

current_library_name()
^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinCurrentLibraryName

current_library_path()
^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinCurrentLibraryPath

field(name)
^^^^^^^^^^^

.. autoclass:: BuiltinField

formats_modtimes(date_format)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinFormatsModtimes

formats_paths()
^^^^^^^^^^^^^^^

.. autoclass:: BuiltinFormatsPaths

formats_sizes()
^^^^^^^^^^^^^^^

.. autoclass:: BuiltinFormatsSizes

has_cover()
^^^^^^^^^^^

.. autoclass:: BuiltinHasCover

language_codes(lang_strings)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinLanguageCodes

language_strings(lang_codes, localize)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinLanguageStrings

ondevice()
^^^^^^^^^^

.. autoclass:: BuiltinOndevice

raw_field(name)
^^^^^^^^^^^^^^^

.. autoclass:: BuiltinRawField

raw_list(name, separator)
^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinRawList

series_sort()
^^^^^^^^^^^^^

.. autoclass:: BuiltinSeriesSort

user_categories()
^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinUserCategories

virtual_libraries()
^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinVirtualLibraries

If-then-else
------------

check_yes_no(field_name, is_undefined, is_false, is_true)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinCheckYesNo

contains(val, pattern, text if match, text if not match)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinContains

ifempty(val, text if empty)
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinIfempty

test(val, text if not empty, text if empty)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinTest

Iterating over values
---------------------

first_non_empty(value, value, ...)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinFirstNonEmpty

lookup(val, pattern, field, pattern, field, ..., else_field)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinLookup

switch(val, pattern, value, pattern, value, ..., else_value)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinSwitch

List lookup
-----------

_identifier_in_list(val, id, found_val, not_found_val)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinIdentifierInList

in_list(val, separator, pattern, found_val, ..., not_found_val)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinInList

list_item(val, index, separator)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinListitem

select(val, key)
^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinSelect

str_in_list(val, separator, string, found_val, ..., not_found_val)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinStrInList

List manipulation
-----------------

count(val, separator)
^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinCount

list_difference(list1, list2, separator)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinListDifference

list_equals(list1, sep1, list2, sep2, yes_val, no_val)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinListEquals

list_intersection(list1, list2, separator)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinListIntersection

list_re(src_list, separator, include_re, opt_replace)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinListRe

list_re_group(src_list, separator, include_re, search_re, group_1_template, ...)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinListReGroup

list_sort(list, direction, separator)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinListSort

list_union(list1, list2, separator)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinListUnion

subitems(val, start_index, end_index)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinSubitems

sublist(val, start_index, end_index, separator)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinSublist

Other
-----

assign(id, val)
^^^^^^^^^^^^^^^

.. autoclass:: BuiltinAssign

print(a, b, ...)
^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinPrint

Recursion
---------

eval(template)
^^^^^^^^^^^^^^

.. autoclass:: BuiltinEval

template(x)
^^^^^^^^^^^

.. autoclass:: BuiltinTemplate

Relational
----------

cmp(x, y, lt, eq, gt)
^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinCmp

first_matching_cmp(val, cmp1, result1, cmp2, r2, ..., else_result)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinFirstMatchingCmp

strcmp(x, y, lt, eq, gt)
^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinStrcmp

String case changes
-------------------

capitalize(val)
^^^^^^^^^^^^^^^

.. autoclass:: BuiltinCapitalize

lowercase(val)
^^^^^^^^^^^^^^

.. autoclass:: BuiltinLowercase

titlecase(val)
^^^^^^^^^^^^^^

.. autoclass:: BuiltinTitlecase

uppercase(val)
^^^^^^^^^^^^^^

.. autoclass:: BuiltinUppercase

String manipulation
-------------------

re(val, pattern, replacement)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinRe

re_group(val, pattern, template_for_group_1, for_group_2, ...)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinReGroup

shorten(val, left chars, middle text, right chars)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinShorten

strcat(a, b, ...)
^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinStrcat

strcat_max(max, string1, prefix2, string2, ...)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinStrcatMax

strlen(a)
^^^^^^^^^

.. autoclass:: BuiltinStrlen

substr(str, start, end)
^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinSubstr

swap_around_articles(val, separator)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinSwapAroundArticles

swap_around_comma(val)
^^^^^^^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinSwapAroundComma

transliterate(a)
^^^^^^^^^^^^^^^^

.. autoclass:: BuiltinTransliterate


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-