Skip to content

Commit

Permalink
Merge branch 'various-small-fix' of https://github.com/un-pogaz/calibre
Browse files Browse the repository at this point in the history
  • Loading branch information
@kovidgoyal
kovidgoyal committed Nov 17, 2024
2 parents e854f08 + 2dceeb0 commit a83d7b0
Showing 1 changed file with 56 additions and 55 deletions.
111 changes: 56 additions & 55 deletions src/calibre/utils/formatter_functions.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -323,8 +323,8 @@ class BuiltinFirstMatchingCmp(BuiltinFormatterFunction):
__doc__ = doc = _(
r'''
``first_matching_cmp(val, [ cmp, result, ]* else_result)`` -- compares ``val < cmp``
in sequence, returning the associated result for the first comparison that
succeeds. Returns else_result if no comparison succeeds.
in sequence, returning the associated ``result`` for the first comparison that
succeeds. Returns ``else_result`` if no comparison succeeds.
Example:
[CODE]
Expand Down Expand Up @@ -352,7 +352,8 @@ class BuiltinStrcat(BuiltinFormatterFunction):
__doc__ = doc = _(
r'''
``strcat(a [, b]*)`` -- can take any number of arguments. Returns a string
formed by concatenating all the arguments.
formed by concatenating all the arguments. In most cases you can use the ``&`` operator
instead of this function.
''')

def evaluate(self, formatter, kwargs, mi, locals, *args):
Expand Down Expand Up @@ -646,6 +647,7 @@ class BuiltinField(BuiltinFormatterFunction):
__doc__ = doc = _(
r'''
``field(lookup_name)`` -- returns the value of the metadata field with lookup name ``lookup_name``.
The ``$`` prefix can be used instead of the function, as in ``$tags``.
''')

def evaluate(self, formatter, kwargs, mi, locals, name):
Expand Down Expand Up @@ -685,7 +687,7 @@ class BuiltinRawList(BuiltinFormatterFunction):
r'''
``raw_list(lookup_name, separator)`` -- returns the metadata list named by
``lookup_name`` without applying any formatting or sorting, with the items
separated by separator.
separated by ``separator``.
''')

def evaluate(self, formatter, kwargs, mi, locals, name, separator):
Expand Down Expand Up @@ -720,7 +722,7 @@ class BuiltinLookup(BuiltinFormatterFunction):
__doc__ = doc = _(
r'''
``lookup(value, [ pattern, key, ]* else_key)`` -- The patterns will be checked against
the value in order. If a pattern matches then the value of the field named by
the ``value`` in order. If a ``pattern`` matches then the value of the field named by
``key`` is returned. If no pattern matches then the value of the field named by
``else_key`` is returned. See also the :ref:`switch` function.
''')
Expand Down Expand Up @@ -748,8 +750,8 @@ class BuiltinTest(BuiltinFormatterFunction):
category = 'If-then-else'
__doc__ = doc = _(
r'''
``test(value, text if not empty, text if empty)`` -- return ``text if not empty`` if
the value is not empty, otherwise return ``text if empty``.
``test(value, text_if_not_empty, text_if_empty)`` -- return ``text_if_not_empty`` if
the value is not empty, otherwise return ``text_if_empty``.
''')

def evaluate(self, formatter, kwargs, mi, locals, val, value_if_set, value_not_set):
Expand All @@ -765,9 +767,9 @@ class BuiltinContains(BuiltinFormatterFunction):
category = 'If-then-else'
__doc__ = doc = _(
r'''
``contains(value, pattern, text if match, text if not match)`` -- checks if the value
is matched by the regular expression ``pattern``. Returns ``text if match`` if
the pattern matches the value, otherwise returns ``text if no match``.
``contains(value, pattern, text_if_match, text_if_not_match)`` -- checks if the value
is matched by the regular expression ``pattern``. Returns ``text_if_match`` if
the pattern matches the value, otherwise returns ``text_if_not_match``.
''')

def evaluate(self, formatter, kwargs, mi, locals,
Expand Down Expand Up @@ -874,7 +876,7 @@ class BuiltinInList(BuiltinFormatterFunction):
__doc__ = doc = _(
r'''
``list_contains(value, separator, [ pattern, found_val, ]* not_found_val)`` -- interpret the
value as a list of items separated by ``separator``, checking the ``pattern``
``value`` as a list of items separated by ``separator``, checking the ``pattern``
against each item in the list. If the ``pattern`` matches an item then return
``found_val``, otherwise return ``not_found_val``. The pair ``pattern`` and
``found_value`` can be repeated as many times as desired, permitting returning
Expand Down Expand Up @@ -910,7 +912,7 @@ class BuiltinStrInList(BuiltinFormatterFunction):
__doc__ = doc = _(
r'''
``str_in_list(value, separator, [ string, found_val, ]+ not_found_val)`` -- interpret
the value as a list of items separated by ``separator`` then compare ``string``
the ``value`` as a list of items separated by ``separator`` then compare ``string``
against each value in the list. The ``string`` is not a regular expression. If
``string`` is equal to any item (ignoring case) then return the corresponding
``found_val``. If ``string`` contains ``separators`` then it is also treated as
Expand Down Expand Up @@ -987,7 +989,7 @@ class BuiltinRe(BuiltinFormatterFunction):
category = 'String manipulation'
__doc__ = doc = _(
r'''
``re(value, pattern, replacement)`` -- return the value after applying the regular
``re(value, pattern, replacement)`` -- return the ``value`` after applying the regular
expression. All instances of ``pattern`` in the value are replaced with
``replacement``. The template language uses case insensitive
[URL href="https://docs.python.org/3/library/re.html"]Python regular
Expand All @@ -1005,7 +1007,7 @@ class BuiltinReGroup(BuiltinFormatterFunction):
__doc__ = doc = _(
r'''
``re_group(value, pattern [, template_for_group]*)`` -- return a string made by
applying the regular expression pattern to ``value`` and replacing each matched
applying the regular expression ``pattern`` to ``value`` and replacing each matched
instance with the value returned by the corresponding template. In
[URL href="https://manual.calibre-ebook.com/template_lang.html#more-complex-programs-in-template-expressions-template-program-mode"]
Template Program Mode[/URL], like for the ``template`` and the
Expand Down Expand Up @@ -1043,9 +1045,9 @@ class BuiltinSwapAroundComma(BuiltinFormatterFunction):
category = 'String manipulation'
__doc__ = doc = _(
r'''
``swap_around_comma(value)`` -- given a value of the form ``B, A``, return ``A B``.
``swap_around_comma(value)`` -- given a ``value`` of the form ``B, A``, return ``A B``.
This is most useful for converting names in LN, FN format to FN LN. If there is
no comma in the value then the function returns the value unchanged.
no comma in the ``value`` then the function returns the value unchanged.
''')

def evaluate(self, formatter, kwargs, mi, locals, val):
Expand All @@ -1058,8 +1060,8 @@ class BuiltinIfempty(BuiltinFormatterFunction):
category = 'If-then-else'
__doc__ = doc = _(
r'''
``ifempty(value, text if empty)`` -- if the value is not empty then return that value,
otherwise return ``text if empty``.
``ifempty(value, text_if_empty)`` -- if the ``value`` is not empty then return that ``value``,
otherwise return ``text_if_empty``.
''')

def evaluate(self, formatter, kwargs, mi, locals, val, value_if_empty):
Expand All @@ -1075,10 +1077,10 @@ class BuiltinShorten(BuiltinFormatterFunction):
category = 'String manipulation'
__doc__ = doc = _(
r'''
``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
``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
Expand Down Expand Up @@ -1151,7 +1153,7 @@ class BuiltinListitem(BuiltinFormatterFunction):
category = 'List lookup'
__doc__ = doc = _(
r'''
``list_item(value, index, separator)`` -- interpret the value as a list of items
``list_item(value, index, separator)`` -- interpret the ``value`` as a list of items
separated by ``separator``, returning the 'index'th item. The first item is
number zero. The last item has the index ``-1`` as in
``list_item(-1,separator)``. If the item is not in the list, then the empty
Expand All @@ -1176,10 +1178,10 @@ class BuiltinSelect(BuiltinFormatterFunction):
category = 'List lookup'
__doc__ = doc = _(
r'''
``select(value, key)`` -- interpret the value as a comma-separated list of items with
``select(value, key)`` -- interpret the ``value`` as a comma-separated list of items with
each item having the form ``id:value`` (the calibre ``identifier`` format). The
function finds the first pair with the id equal to key and returns the
corresponding value. If no id matches then the function returns the empty
function finds the first pair with the id equal to ``key`` and returns the
corresponding ``value``. If no id matches then the function returns the empty
string.
''')

Expand Down Expand Up @@ -1294,7 +1296,7 @@ class BuiltinHumanReadable(BuiltinFormatterFunction):
category = 'Formatting values'
__doc__ = doc = _(
r'''
``human_readable(value)`` -- expects the value to be a number and returns a string
``human_readable(value)`` -- expects the ``value`` to be a number and returns a string
representing that number in KB, MB, GB, etc.
''')

Expand All @@ -1311,7 +1313,7 @@ class BuiltinFormatNumber(BuiltinFormatterFunction):
category = 'Formatting values'
__doc__ = doc = _(
r'''
``format_number(value, template)`` -- interprets the value as a number and formats that
``format_number(value, template)`` -- interprets the ``value`` as a number and formats that
number using a Python formatting template such as ``{0:5.2f}`` or ``{0:,d}`` or
``${0:5,.2f}``. The formatting template must begin with ``{0:`` and end with
``}`` as in the above examples. Exception: you can leave off the leading "{0:"
Expand Down Expand Up @@ -1350,7 +1352,7 @@ class BuiltinSublist(BuiltinFormatterFunction):
category = 'List manipulation'
__doc__ = doc = _(
r'''
``sublist(value, start_index, end_index, separator)`` -- interpret the value as a
``sublist(value, start_index, end_index, separator)`` -- interpret the ``value`` as a
list of items separated by ``separator``, returning a new list made from the
items from ``start_index`` to ``end_index``. The first item is number zero. If
an index is negative, then it counts from the end of the list. As a special
Expand Down Expand Up @@ -1390,13 +1392,13 @@ class BuiltinSubitems(BuiltinFormatterFunction):
__doc__ = doc = _(
r'''
``subitems(value, start_index, end_index)`` -- This function breaks apart lists of
tag-like hierarchical items such as genres. It interprets the value as a comma-
tag-like hierarchical items such as genres. It interprets the ``value`` as a comma-
separated list of tag-like items, where each item is a period-separated list. It
returns a new list made by extracting from each item the components from
``start_index`` to ``end_index``, then merging the results back together.
Duplicates are removed. The first subitem in a period-separated list has an
index of zero. If an index is negative then it counts from the end of the list.
As a special case, an end_index of zero is assumed to be the length of the list.
As a special case, an ``end_index`` of zero is assumed to be the length of the list.
Examples:
[LIST]
Expand Down Expand Up @@ -1447,8 +1449,8 @@ class BuiltinFormatDate(BuiltinFormatterFunction):
category = 'Formatting values'
__doc__ = doc = _(
r'''
``format_date(value, format_string)`` -- format the value, which must be a date
string, using the format_string, returning a string. It is best if the date is
``format_date(value, format_string)`` -- format the ``value``, which must be a date
string, using the ``format_string``, returning a string. It is best if the date is
in ISO format as using other date formats often causes errors because the actual
date value cannot be unambiguously determined. Note that the
``format_date_field()`` function is both faster and more reliable.
Expand Down Expand Up @@ -1557,7 +1559,7 @@ class BuiltinUppercase(BuiltinFormatterFunction):
category = 'String case changes'
__doc__ = doc = _(
r'''
``uppercase(value)`` -- returns the value in upper case.
``uppercase(value)`` -- returns the ``value`` in upper case.
''')

def evaluate(self, formatter, kwargs, mi, locals, val):
Expand All @@ -1570,7 +1572,7 @@ class BuiltinLowercase(BuiltinFormatterFunction):
category = 'String case changes'
__doc__ = doc = _(
r'''
``lowercase(value)`` -- returns the value in lower case.
``lowercase(value)`` -- returns the ``value`` in lower case.
''')

def evaluate(self, formatter, kwargs, mi, locals, val):
Expand All @@ -1583,7 +1585,7 @@ class BuiltinTitlecase(BuiltinFormatterFunction):
category = 'String case changes'
__doc__ = doc = _(
r'''
``titlecase(value)`` -- returns the value in title case.
``titlecase(value)`` -- returns the ``value`` in title case.
''')

def evaluate(self, formatter, kwargs, mi, locals, val):
Expand All @@ -1596,7 +1598,7 @@ class BuiltinCapitalize(BuiltinFormatterFunction):
category = 'String case changes'
__doc__ = doc = _(
r'''
``capitalize(value)`` -- returns the value with the first letter in upper case and the rest lower case.
``capitalize(value)`` -- returns the ``value`` with the first letter in upper case and the rest lower case.
''')

def evaluate(self, formatter, kwargs, mi, locals, val):
Expand Down Expand Up @@ -1877,8 +1879,8 @@ class BuiltinRange(BuiltinFormatterFunction):
__doc__ = doc = _(
r'''
``range(start, stop, step, limit)`` -- returns a list of numbers generated by
looping over the range specified by the parameters start, stop, and step, with a
maximum length of limit. The first value produced is 'start'. Subsequent values
looping over the range specified by the parameters ``start``, ``stop``, and ``step``,
with a maximum length of ``limit``. The first value produced is 'start'. Subsequent values
``next_v = current_v + step``. The loop continues while ``next_v < stop``
assuming ``step`` is positive, otherwise while ``next_v > stop``. An empty list
is produced if ``start`` fails the test: ``start >= stop`` if ``step`` is
Expand Down Expand Up @@ -1950,7 +1952,7 @@ class BuiltinListDifference(BuiltinFormatterFunction):
r'''
``list_difference(list1, list2, separator)`` -- return a list made by removing
from ``list1`` any item found in ``list2`` using a case-insensitive comparison.
The items in ``list1`` and ``list2`` are separated by separator, as are the
The items in ``list1`` and ``list2`` are separated by ``separator``, as are the
items in the returned list.
''')

Expand All @@ -1975,7 +1977,7 @@ class BuiltinListIntersection(BuiltinFormatterFunction):
r'''
``list_intersection(list1, list2, separator)`` -- return a list made by removing
from ``list1`` any item not found in ``list2``, using a case-insensitive
comparison. The items in ``list1`` and ``list2`` are separated by separator, as
comparison. The items in ``list1`` and ``list2`` are separated by ``separator``, as
are the items in the returned list.
''')

Expand Down Expand Up @@ -2152,7 +2154,7 @@ class BuiltinDateArithmetic(BuiltinFormatterFunction):
r'''
``date_arithmetic(value, calc_spec, fmt)`` -- Calculate a new date from ``value``
using ``calc_spec``. Return the new date formatted according to optional
``fmt``: if not supplied then the result will be in ISO format. The calc_spec is
``fmt``: if not supplied then the result will be in ISO format. The ``calc_spec`` is
a string formed by concatenating pairs of ``vW`` (``valueWhat``) where ``v`` is
a possibly-negative number and W is one of the following letters:
[LIST]
Expand Down Expand Up @@ -2282,8 +2284,8 @@ class BuiltinFinishFormatting(BuiltinFormatterFunction):
category = 'Formatting values'
__doc__ = doc = _(
r'''
``finish_formatting(val, format, prefix, suffix)`` -- apply the ``format``, ``prefix``, and
``suffix`` to a value in the same way as done in a template like
``finish_formatting(value, format, prefix, suffix)`` -- apply the ``format``, ``prefix``, and
``suffix`` to the ``value`` in the same way as done in a template like
``{series_index:05.2f| - |- }``. This function is provided to ease conversion of
complex single-function- or template-program-mode templates to `GPM` Templates.
For example, the following program produces the same output as the above
Expand Down Expand Up @@ -2606,9 +2608,9 @@ class BuiltinRatingToStars(BuiltinFormatterFunction):
category = 'Formatting values'
__doc__ = doc = _(
r'''
``rating_to_stars(value, use_half_stars)`` -- Returns the value as string of star
(``{}``) characters. The value must be a number between 0 and 5. Set
use_half_stars to 1 if you want half star characters for fractional numbers
``rating_to_stars(value, use_half_stars)`` -- Returns the ``value`` as string of star
(``{}``) characters. The value must be a number between ``0`` and ``5``. Set
``use_half_stars`` to ``1`` if you want half star characters for fractional numbers
available with custom ratings columns.
''').format('★')

Expand All @@ -2632,10 +2634,10 @@ class BuiltinSwapAroundArticles(BuiltinFormatterFunction):
category = 'String manipulation'
__doc__ = doc = _(
r'''
``swap_around_articles(value, separator)`` -- returns the value with articles moved to
the end. The value can be a list, in which case each item in the list is
processed. If the value is a list then you must provide the ``separator``. If no
``separator`` is provided then the value is treated as being a single value, not
``swap_around_articles(value, separator)`` -- returns the ``value`` with articles moved to
the end. The ``value`` can be a list, in which case each item in the list is
processed. If the ``value`` is a list then you must provide the ``separator``. If no
``separator`` is provided then the ``value`` is treated as being a single value, not
a list. The `articles` are those used by calibre to generate the ``title_sort``.
''')

Expand Down Expand Up @@ -2768,7 +2770,7 @@ class BuiltinUrlsFromIdentifiers(BuiltinFormatterFunction):
``urls_from_identifiers(identifiers, sort_results)`` -- given a comma-separated
list of ``identifiers``, where an ``identifier`` is a colon-separated pair of
values (``id_name:id_value``), returns a comma-separated list of HTML URLs
generated from the identifiers. The list not sorted if sort_results is ``0``
generated from the identifiers. The list not sorted if ``sort_results`` is ``0``
(character or number), otherwise it is sorted alphabetically by the identifier
name. The URLs are generated in the same way as the built-in identifiers column
when shown in Book Details.
Expand Down Expand Up @@ -3020,7 +3022,7 @@ class BuiltinGetNote(BuiltinFormatterFunction):
__doc__ = doc = _(
r'''
``get_note(field_name, field_value, plain_text)`` -- fetch the note for field
'field_name' with value 'field_value'. If ``plain_text`` is empty, return the
``field_name`` with value ``field_value``. If ``plain_text`` is empty, return the
note's HTML including images. If ``plain_text`` is ``1`` (or ``'1'``), return the
note's plain text. If the note doesn't exist, return the empty string in both
cases. Example:
Expand Down Expand Up @@ -3159,8 +3161,7 @@ class BuiltinFieldListCount(BuiltinFormatterFunction):
the lookup name ``lookup_name``. The field must be multi-valued such as
``authors`` or ``tags``, otherwise the function raises an error. This function
is much faster than ``list_count()`` because it operates directly on calibre
data without converting it to a string first. Example:
``list_count_field('tags')``
data without converting it to a string first. Example: ``list_count_field('tags')``.
''')

def evaluate(self, formatter, kwargs, mi, locals, *args):
Expand Down

0 comments on commit a83d7b0

Please sign in to comment.