Append final user replace regex-function output to marked text (see #1609111)

Introduces a new flag "append_final_output_to_marked".
Depends also on existing flag "call_after_last_match".

Following two lines at the end of a user replace function will cause,
that the return value of the last additional call (after all replacements
are completed) will be appended to the marked text:
replace.call_after_last_match = True
replace.append_final_output_to_marked = True

TODO: Documentation update is required.
Part: Editing books
Chapter: Function Mode for Search & Replace in the Editor
Section: Having your function called an extra time after the last match is found

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())