diffobj (version 0.1.2)

Pager: Objects for Specifying Pager Settings

Description

Generate pager configuration objects to use as the pager argument to the diff* methods or as the pager slot for Style objects.

Usage

PagerOff(...)
PagerSystem(pager = file.show, threshold = -1L, file.ext = "", ...)
PagerSystemLess(pager = file.show, threshold = -1L, file.ext = "", flags = "R", ...)
PagerBrowser(pager = make_blocking(browseURL), threshold = 0L, file.ext = "html", ...)

Arguments

...

additional arguments to pass on to new, typically not used

pager

a function that accepts at least one parameter and does not require a parameter other than the first parameter. This function will be called with a file name passed as the first argument. The referenced file will contain the text of the diff. This is a temporary file that will be deleted as soon as the pager function completes evaluation. PagerSystem and PagerSystemLess use file.show by default, and PagerBrowser uses browseURL.

threshold

integer(1L) number of lines of output that triggers the use of the pager; negative values lead to using console_lines + 1, and zero leads to always using the pager irrespective of how many lines the output has.

file.ext

character(1L) an extension to append to file name passed to pager, without the period. For example, PagerBrowser uses “html” to cause browseURL to launch the web browser.

flags

character(1L), only for PagerSystemLess, what flags to set with the LESS system environment variable. By default the “R” flag is set to ensure ANSI escape sequences are interpreted if it appears your terminal supports ANSI escape sequences. If you want to leave the output on the screen after you exit the pager you can use “RX”. You should only provide the flag letters (e.g. “"RX"”, not "-RX"). The system variable is only modified for the duration of the evaluation and is reset / unset afterwards. Note: you must specify this slot via the constructor as in the example. If you set the slot directly it will not have any effect.

Custom Pagers

If you wish to define your own pager object you should do so by extending the Pager virtual class. In most cases you should be able to use one of the existing objects configured with different parameters, but if your pager function requires special treatment then you can define a custom pager object. At a minimum you should specify the pager slot of the object (see constructor function parameter definition). If the function you use to handle the actual paging is non-blocking (i.e. allows R code evaluation to continue after it is spawned, you may want to wrap it in a function that pauses evaluation such as make_blocking, as otherwise the temporary file that contains the diff may be deleted before the pager has a chance to read it.

Details

Several pre-defined pager configuration objects are available via constructor functions:

• PagerOff: Turn off pager
• PagerSystem: Use the system pager as invoked by file.show
• PagerSystemLess: Like PagerSystem, but provides additional configuration options if it the system pager is less
• PagerBrowser: Use browseURL as the pager

Make sure you instantiate the pagers with the constructor functions rather than with new to make sure they are properly configured.

Examples

## Assuming system pager is `less` and terminal supports ANSI ESC sequences
## Equivalent to running `less -RFX`
diffPrint(letters, LETTERS, pager=PagerSystemLess(flags="RFX"))