tui: open log files in external application

* Allow log files to be open in external applications.
* Tui will suspend whilst the external tool is open, and resume once it
  has closed.
* Options implemented are `$EDITOR`, `$GEDITOR`, `$PAGER` and `vim` as a
  backup.

Author: oliver-sanders

changes.d/6611.feat.md

@@ -0,0 +1 @@
+Tui: Add ability to open log files in external tools. Configure your `$EDITOR`, `$GEDITOR` or `$PAGER` options to configure which tool is used.

cylc/flow/tui/overlay.py

@@ -38,8 +38,14 @@
 """
 
 from functools import partial
+import os
 import re
+import shlex
+import stat
+from subprocess import Popen
 import sys
+import tempfile
+from time import sleep
 
 import urwid
 
@@ -473,6 +479,56 @@ def open_log(*_, filename=None, close=False):
             if close:
                 app.close_topmost()
 
+    def open_in_editor(*_, command):
+        """Suspend Tui, open the file in an external utility, then restore Tui.
+
+        Args:
+            command:
+                The command to run as a list, e.g. 'gvim -f'.
+                This command must be blocking, the tui session will be
+                restored when the command exits.
+
+        """
+        nonlocal text_widget
+
+        with tempfile.NamedTemporaryFile('w+') as temp_file:
+            # write the text into a temp file
+            temp_file.write(text_widget.text)
+            temp_file.seek(0, 0)
+
+            # make the file readonly to avoid confusion
+            os.chmod(temp_file.name, stat.S_IRUSR)
+
+            # suspend Tui
+            app.loop.screen.stop()
+
+            # open the file using the external tool (must be blocking)
+            print(
+                'Launching external tool, Tui will resume once it exits.',
+                file=sys.stderr,
+            )
+            try:
+                Popen(
+                    [*shlex.split(command), temp_file.name]
+                ).wait()  # nosec B603
+                # (this is running a command the user has configured)
+            except OSError as exc:
+                # ensure any critical errors are visible to the user so
+                # that they have a chance to fix them
+                _sleep_time = 5
+                print(
+                    (
+                        f'Error running {command} {temp_file.name}'
+                        f'\n{exc}'
+                        f'\nTui will resume in {_sleep_time} seconds'
+                    ),
+                    file=sys.stderr
+                )
+                sleep(_sleep_time)
+
+            # restore Tui
+            app.loop.screen.start()
+
     # load the default log file
     if id_:
         # NOTE: the kwargs are not provided in the overlay unit tests
@@ -489,6 +545,25 @@ def open_log(*_, filename=None, close=False):
                 'Select File',
                 on_press=open_menu,
             ),
+            urwid.Columns([
+                ('pack', urwid.Text('Open in:  ')),
+                *(
+                    (
+                        'pack',
+                        urwid.Button(
+                            label,
+                            align='left',
+                            on_press=partial(open_in_editor, command=command),
+                        ),
+                    )
+                    for label, command in (
+                        ('$EDITOR', os.environ.get('EDITOR', 'vim')),
+                        ('$GEDITOR', os.environ.get('GEDITOR', 'gvim -f')),
+                        ('$PAGER', os.environ.get('PAGER', 'less')),
+                        ('vim', 'vim'),
+                    )
+                ),
+            ]),
             urwid.Divider(),
             text_widget,
         ]),

tests/integration/tui/screenshots/test_errors.list-error.html

@@ -2,7 +2,7 @@
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">Error: Somethi</span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">Error                                       </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">              </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                            </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">&lt;</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">Select File </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">Something went wrong :(                     </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">        </span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">&gt;</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
-<span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">              </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                            </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
+<span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">Open in:  </span><span style="color:#000000;background:#e5e5e5">&lt;</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">$E</span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                            </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">              </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                            </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">              </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                            </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">              </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                            </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>

tests/integration/tui/screenshots/test_errors.open-error.html

@@ -2,7 +2,7 @@
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">Error: Something went wrong :(                                            </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                                                          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">&lt;</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5"></span><span style="color:#e5e5e5;background:#000000">S</span><span style="color:#000000;background:#e5e5e5">elect File                                                           </span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">&gt;</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
-<span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                                                          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
+<span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">Open in:  </span><span style="color:#000000;background:#e5e5e5">&lt;</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">$EDITOR</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">&gt;</span><span style="color:#000000;background:#e5e5e5">&lt;</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">$GEDITOR</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">&gt;</span><span style="color:#000000;background:#e5e5e5">&lt;</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">$PAGER</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">&gt;</span><span style="color:#000000;background:#e5e5e5">&lt;</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">vim</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">&gt;</span><span style="color:#000000;background:#e5e5e5">                        </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                                                          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                                                          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                                                          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>