Added pager settable parameter to control the command used to display paged output

Also:
- ppaged() now uses the pager settable parameter
- By default the pager settable parameter uses the PAGER environment variable if present
- If PAGER environment variable is not present, pager gets set to:
    - "less -SXRF" on POSIX OSes (macOS and Linux)
    - "more" on Windows

Author: tleonhardt

CHANGELOG.md

@@ -3,6 +3,8 @@
     * Fixed issue where piping and redirecting did not work correctly with paths that had spaces
 * Enhancements
     * Added ability to print a header above tab-completion suggestions using `completion_header` member
+    * **pager** is now a settable parameter which controls pager command used by ``cmd2.Cmd.ppaged`` method
+        * **pager** looks for *PAGER* environment variable if present or uses sane defaults if not
 
 ## 0.8.8 (TBD, 2018)
 * Bug Fixes

cmd2/cmd2.py

@@ -385,6 +385,17 @@ class Cmd(cmd.Cmd):
                     break
     feedback_to_output = False  # Do not include nonessentials in >, | output by default (things like timing)
     locals_in_py = False
+    pager = os.environ.get('PAGER')
+    if not pager:
+        if sys.platform.startswith('win'):
+            pager = 'more'
+        else:
+            # Here is the meaning of the various flags we are using with the less command:
+            # -S causes lines longer than the screen width to be chopped (truncated) rather than wrapped
+            # -R causes ANSI "color" escape sequences to be output in raw form (i.e. colors are displayed)
+            # -X disables sending the termcap initialization and deinitialization strings to the terminal
+            # -F causes less to automatically exit if the entire file can be displayed on the first screen
+            pager = 'less -SRXF'
     quiet = False  # Do not suppress nonessential output
     timing = False  # Prints elapsed time for each command
 
@@ -397,6 +408,7 @@ class Cmd(cmd.Cmd):
                 'editor': 'Program used by ``edit``',
                 'feedback_to_output': 'Include nonessentials in `|`, `>` results',
                 'locals_in_py': 'Allow access to your application in py via self',
+                'pager': 'Command used for displaying paged output',
                 'prompt': 'The prompt issued to solicit input',
                 'quiet': "Don't print nonessential feedback",
                 'timing': 'Report execution times'}
@@ -635,17 +647,7 @@ def ppaged(self, msg: str, end: str='\n') -> None:
                 # Don't attempt to use a pager that can block if redirecting or running a script (either text or Python)
                 # Also only attempt to use a pager if actually running in a real fully functional terminal
                 if functional_terminal and not self.redirecting and not self._in_py and not self._script_dir:
-
-                    if sys.platform.startswith('win'):
-                        pager_cmd = 'more'
-                    else:
-                        # Here is the meaning of the various flags we are using with the less command:
-                        # -S causes lines longer than the screen width to be chopped (truncated) rather than wrapped
-                        # -R causes ANSI "color" escape sequences to be output in raw form (i.e. colors are displayed)
-                        # -X disables sending the termcap initialization and deinitialization strings to the terminal
-                        # -F causes less to automatically exit if the entire file can be displayed on the first screen
-                        pager_cmd = 'less -SRXF'
-                    self.pipe_proc = subprocess.Popen(pager_cmd, shell=True, stdin=subprocess.PIPE)
+                    self.pipe_proc = subprocess.Popen(self.pager, shell=True, stdin=subprocess.PIPE)
                     try:
                         self.pipe_proc.stdin.write(msg_str.encode('utf-8', 'replace'))
                         self.pipe_proc.stdin.close()

examples/paged_output.py

@@ -2,26 +2,35 @@
 # coding=utf-8
 """A simple example demonstrating the using paged output via the ppaged() method.
 """
+import os
+from typing import List
 
 import cmd2
 
 
 class PagedOutput(cmd2.Cmd):
-    """ Example cmd2 application where we create commands that just print the arguments they are called with."""
+    """ Example cmd2 application which shows how to display output using a pager."""
 
     def __init__(self):
         super().__init__()
 
     @cmd2.with_argument_list
-    def do_page_file(self, args):
-        """Read in a text file and display its output in a pager."""
+    def do_page_file(self, args: List[str]):
+        """Read in a text file and display its output in a pager.
+
+        Usage: page_file <file_path>
+        """
         if not args:
             self.perror('page_file requires a path to a file as an argument', traceback_war=False)
             return
 
-        with open(args[0], 'r') as f:
-            text = f.read()
-        self.ppaged(text)
+        filename = os.path.expanduser(args[0])
+        try:
+            with open(filename, 'r') as f:
+                text = f.read()
+            self.ppaged(text)
+        except FileNotFoundError as ex:
+            self.perror('ERROR: file {!r} not found'.format(filename), traceback_war=False)
 
     complete_page_file = cmd2.Cmd.path_complete
 

tests/conftest.py

@@ -80,8 +80,10 @@
 """
 
 expect_colors = True
+pager = 'less -SRXF'
 if sys.platform.startswith('win'):
     expect_colors = False
+    pager = 'more'
 # Output from the show command with default settings
 SHOW_TXT = """colors: {}
 continuation_prompt: >
@@ -90,10 +92,11 @@
 editor: vim
 feedback_to_output: False
 locals_in_py: False
+pager: {}
 prompt: (Cmd)
 quiet: False
 timing: False
-""".format(expect_colors)
+""".format(expect_colors, pager)
 
 if expect_colors:
     color_str = 'True '
@@ -107,10 +110,11 @@
 editor: vim               # Program used by ``edit``
 feedback_to_output: False # Include nonessentials in `|`, `>` results
 locals_in_py: False       # Allow access to your application in py via self
+pager: {}         # Command used for displaying paged output
 prompt: (Cmd)             # The prompt issued to solicit input
 quiet: False              # Don't print nonessential feedback
 timing: False             # Report execution times
-""".format(color_str)
+""".format(color_str, pager)
 
 
 class StdOut(object):

tests/transcripts/regex_set.txt

@@ -12,6 +12,7 @@ editor: /.*/
 feedback_to_output: False
 locals_in_py: False
 maxrepeats: 3
+pager: /.*/
 prompt: (Cmd)/ /
 quiet: False
 timing: False