Edit book: Function mode: Allow appending text to the end of the marked text when running function mode search/replace on marked text

Merge branch 'regexfn_return_value' of https://github.com/Mymei2/calibre

manual/function_mode.rst

@@ -370,3 +370,21 @@ function, like this:
         ...
 
     replace.call_after_last_match = True
+
+
+Appending the output from the function to marked text
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When running search and replace on marked text, it is sometimes useful to
+append so text to the end of the marked text. You can do that by setting
+the ``append_final_output_to_marked`` attribute on your function (note that you
+also need to set ``call_after_last_match``), like this:
+
+.. code-block:: python
+
+    def replace(match, number, file_name, metadata, dictionaries, data, functions, *args, **kwargs):
+        ...
+        return 'some text to append'
+
+    replace.call_after_last_match = True
+    replace.append_final_output_to_marked = True

src/calibre/gui2/tweak_book/editor/text.py

@@ -313,7 +313,12 @@ class TextEdit(PlainTextEdit):
             raw, count = pat.subn(template, raw)
             if repl_is_func:
                 from calibre.gui2.tweak_book.search import show_function_debug_output
-                template.end()
+                if getattr(template.func, 'append_final_output_to_marked', False):
+                    retval = template.end()
+                    if retval:
+                        raw += unicode(retval)
+                else:
+                    template.end()
                 show_function_debug_output(template)
             if count > 0:
                 start_pos = min(c.anchor(), c.position())