New formatter function "approximate_formats()". Add functions to manual.

manual/template_lang.rst

@@ -240,9 +240,11 @@ The following functions are available in addition to those described in single-f
     * ``and(value, value, ...)`` -- returns the string "1" if all values are not empty, otherwise returns the empty string. This function works well with test or first_non_empty. You can have as many values as you want.
     * ``add(x, y)`` -- returns x + y. Throws an exception if either x or y are not numbers.
     * ``assign(id, val)`` -- assigns val to id, then returns val. id must be an identifier, not an expression
+    * ``approximate_formats()`` -- return a comma-separated list of formats that at one point were associated with the book. There is no guarantee that the list is correct, although it probably is. This function can be called in template program mode using the template ``{:'approximate_formats()'}``. Note that format names are always uppercase, as in EPUB.
     * ``booksize()`` -- returns the value of the |app| 'size' field. Returns '' if there are no formats.
     * ``cmp(x, y, lt, eq, gt)`` -- compares x and y after converting both to numbers. Returns ``lt`` if x < y. Returns ``eq`` if x == y. Otherwise returns ``gt``.
     * ``current_library_name() -- `` return the last name on the path to the current calibre library. This function can be called in template program mode using the template ``{:'current_library_name()'}``.
+    * ``current_library_path() -- `` eturn the path to the current calibre library. This function can be called in template program mode using the template ``{:'current_library_path()'}``..
     * ``days_between(date1, date2)`` -- return the number of days between ``date1`` and ``date2``. The number is positive if ``date1`` is greater than ``date2``, otherwise negative. If either ``date1`` or ``date2`` are not dates, the function returns the empty string.
     * ``divide(x, y)`` -- returns x / y. Throws an exception if either x or y are not numbers.
     * ``eval(string)`` -- evaluates the string as a program, passing the local variables (those ``assign`` ed to). This permits using the template processor to construct complex results from local variables. Because the `{` and `}` characters are special, you must use `[[` for the `{` character and `]]` for the '}' character; they are converted automatically. Note also that prefixes and suffixes (the `|prefix|suffix` syntax) cannot be used in the argument to this function when using template program mode.
@@ -284,6 +286,7 @@ The following functions are available in addition to those described in single-f
             )
             
     * ``formats_modtimes(date_format)`` -- return a comma-separated list of colon_separated items representing modification times for the formats of a book. The date_format parameter specifies how the date is to be formatted. See the date_format function for details. You can use the select function to get the mod time for a specific format. Note that format names are always uppercase, as in EPUB.
+    * ``formats_paths()`` -- return a comma-separated list of colon_separated items representing full path to the formats of a book. You can use the select function to get the path for a specific format. Note that format names are always uppercase, as in EPUB.
     * ``formats_sizes()`` -- return a comma-separated list of colon_separated items representing sizes in bytes of the formats of a book. You can use the select function to get the size for a specific format. Note that format names are always uppercase, as in EPUB.
     * ``has_cover()`` -- return ``Yes`` if the book has a cover, otherwise return the empty string
     * ``not(value)`` -- returns the string "1" if the value is empty, otherwise returns the empty string. This function works well with test or first_non_empty. You can have as many values as you want.

src/calibre/library/database2.py

@@ -1004,6 +1004,7 @@ class LibraryDatabase2(LibraryDatabase, SchemaUpgrade, CustomColumns):
             mi.format_metadata = FormatMetadata(self, idx, formats)
             good_formats = FormatsList(formats, mi.format_metadata)
         mi.formats = good_formats
+        mi.db_approx_formats = formats
         tags = row[fm['tags']]
         if tags:
             mi.tags = [i.strip() for i in tags.split(',')]

src/calibre/utils/formatter_functions.py

@@ -593,6 +593,24 @@ class BuiltinSelect(BuiltinFormatterFunction):
                 return v[len(key)+1:]
         return ''
 
+class BuiltinApproximateFormats(BuiltinFormatterFunction):
+    name = 'approximate_formats'
+    arg_count = 0
+    category = 'Get values from metadata'
+    __doc__ = doc = _('approximate_formats() -- return a comma-separated '
+                  'list of formats that at one point were associated with the '
+                  'book. There is no guarantee that this list is correct, '
+                  'although it probably is. '
+                  'This function can be called in template program mode using '
+                  'the template "{:\'approximate_formats()\'}. '
+                  'Note that format names are always uppercase, as in EPUB.'
+            )
+
+    def evaluate(self, formatter, kwargs, mi, locals):
+        fmt_data = mi.get('db_approx_formats', [])
+        data = sorted(fmt_data)
+        return ','.join(v.upper() for v in data)
+
 class BuiltinFormatsModtimes(BuiltinFormatterFunction):
     name = 'formats_modtimes'
     arg_count = 1
@@ -633,12 +651,12 @@ class BuiltinFormatsPaths(BuiltinFormatterFunction):
     name = 'formats_paths'
     arg_count = 0
     category = 'Get values from metadata'
-    __doc__ = doc = _('formats_paths() -- return a comma-separated list of '
+        __doc__ = doc = _('formats_paths() -- return a comma-separated list of '
-                      'colon_separated items representing full path to '
+                          'colon_separated items representing full path to '
-                      'the formats of a book. You can use the select '
+                          'the formats of a book. You can use the select '
-                      'function to get the path for a specific '
+                          'function to get the path for a specific '
-                      'format. Note that format names are always uppercase, '
+                          'format. Note that format names are always uppercase, '
-                      'as in EPUB.'
+                          'as in EPUB.'
             )
 
     def evaluate(self, formatter, kwargs, mi, locals):
@@ -1167,9 +1185,9 @@ class BuiltinCurrentLibraryPath(BuiltinFormatterFunction):
     arg_count = 0
     category = 'Get values from metadata'
     __doc__ = doc = _('current_library_path() -- '
-            'return the path to the current calibre library. This function can '
+                'return the path to the current calibre library. This function can '
-            'be called in template program mode using the template '
+                'be called in template program mode using the template '
-            '"{:\'current_library_path()\'}".')
+                '"{:\'current_library_path()\'}".')
     def evaluate(self, formatter, kwargs, mi, locals):
         from calibre.library import current_library_path
         return current_library_path()
@@ -1191,9 +1209,10 @@ class BuiltinFinishFormatting(BuiltinFormatterFunction):
         return prefix + formatter._do_format(val, fmt) + suffix
 
 _formatter_builtins = [
-    BuiltinAdd(), BuiltinAnd(), BuiltinAssign(), BuiltinBooksize(),
+    BuiltinAdd(), BuiltinAnd(), BuiltinApproximateFormats(),
+    BuiltinAssign(), BuiltinBooksize(),
     BuiltinCapitalize(), BuiltinCmp(), BuiltinContains(), BuiltinCount(),
-    BuiltinCurrentLibraryName(),
+    BuiltinCurrentLibraryName(), BuiltinCurrentLibraryPath(),
     BuiltinDaysBetween(), BuiltinDivide(), BuiltinEval(), BuiltinFirstNonEmpty(),
     BuiltinField(), BuiltinFinishFormatting(), BuiltinFormatDate(),
     BuiltinFormatNumber(), BuiltinFormatsModtimes(), BuiltinFormatsPaths(),