Objects for Specifying Pager Settings

Share:

Description

Modify use of pager behavior with pager configuration objects to use as the pager argument to the diff* methods or as the pager slot for Style objects. Note that in this documentation we use the “pager” term loosely and intend it to refer to any device other than the terminal that can be used to render output.

Usage

1
2
3
4
5
6
7
8
9
PagerOff(...)

PagerSystem(pager = file.show, threshold = -1L, file.ext = "", ...)

PagerSystemLess(pager = file.show, threshold = -1L, file.ext = "",
  flags = "R", ansi = TRUE, ...)

PagerBrowser(pager = make_blocking(view_or_browse), 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 make_blocking(view_or_browse). Note that make_blocking ensures that the temporary file is not deleted before the pager can access it.

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.

ansi

TRUE or FALSE, whether the pager supports ANSI escape sequences.

Default Output Behavior

diff* methods use “pagers” to help manage large outputs and also to provide an alternative colored diff when the terminal does not support them directly.

For OS X and *nix systems where less is the pager and the terminal supports ANSI escape sequences, output is colored with ANSI escape sequences. If the output exceeds one screen height in size (as estimated by console_lines) it is sent to the pager.

If the terminal does not support ANSI escape sequences, or if the system pager is not less as detected by pager_is_less, then the output is rendered in HTML and sent to the IDE viewer (getOption("viewer")) if defined, or to the browser with browseURL if not. This behavior may seem sub-optimal for systems that have ANSI aware terminals and ANSI aware pagers other than less, but these should be rare and it is possible to configure diffobj to produce the correct output for them (see examples).

Pagers and Styles

There is a close relationship between pagers and Style. The Style objects control whether the output is raw text, formatted with ANSI escape sequences, or marked up with HTML. In order for these different types of outputs to render properly, they need to be sent to the right device. For this reason Style objects come with a Pager configuration object pre-assigned so the output can render correctly. The exact Pager configuration object depends on the Style as well as the system configuration.

In any call to the diff* methods you can always specify both the Style and Pager configuration object directly for full control of output formatting and rendering. We have tried to set-up sensible defaults for most likely use cases, but given the complex interactions involved it is possible you may need to configure things explicitly. Should you need to define explicit configurations you can save them as option values with options(diffobj.pager=..., diffobj.style=...) so that you do not need to specify them each time you use diffobj.

Pager Configuration Objects

The Pager configuration objects allow you to specify what device to use as the pager and under what circumstances the pager should be used. 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 the system pager is less. Note this object does not change the system pager; it only allows you to configure it via the $LESS environment variable which will have no effect unless the system pager is set to be less.

  • PagerBrowser: Use getOption("viewer") if defined, or browseURL if not

Important: Make sure you instantiate the pager objects with the constructor functions (e.g. PagerSystemLess(...) not new('PagerSystemLess', ...) rather than with new as otherwise they will not be properly configured.

The default configuration for PagerSystem and PagerSystemLess leads to output being sent to the pager if it exceeds the estimated window size, whereas PagerBrowser always sends output to the pager. This behavior can be configured via the threshold parameter.

PagerSystemLess's primary role is to correctly configure the $LESS system variable so that less renders the ANSI escape sequences as intended. On OS X more is a faux-alias to less of sorts, except it does not appear to read the $LESS system variable. Should you configure your system pager to be the more version of less, pager_is_less will be tricked into thinking you are using a “normal” version of less and you will likely end up seeing gibberish in the pager. If this is your use case you will need to set-up a custom pager configuration object that sets the correct system variables.

Custom Pager Configurations

In most cases the simplest way to generate new pager configurations is to start with one of the existing configuration objects. For example, if you wanted to tell diffobj that your default system pager supports ANSI escape sequences despite not being less you could use diffPrint(a, b, pager=PagerSystem(ansi=TRUE).

You can change what system pager is used by changing it with options(pager=... or by changing the $PAGER environment variable. You can also explicitly set a function to act as the pager when you instantiate the Pager configuration object (see examples).

If you wish to define your own pager object you should do so by extending the Pager virtual class. 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.

See Also

Style, pager_is_less

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
## We `dontrun` these examples as they involve pagers that should only be run
## in interactive mode
## Not run: 
## Assuming system pager is `less` and terminal supports ANSI ESC sequences
## Equivalent to running `less -RFX`

diffChr(1:200, 180:300, pager=PagerSystemLess(flags="RFX"))

## System pager is not less, but it supports ANSI escape sequences

diffChr(1:200, 180:300, pager=PagerSystem(ansi=TRUE))

## Use a custom pager, in this case we make up a trivial one and configure it
## always page (`threshold=0L`)

page.fun <- function(x) cat(paste0("| ", readLines(x)), sep="\n")
page.conf <- PagerSystem(pager=page.fun, threshold=0L)
diffChr(1:200, 180:300, pager=page.conf, width=getOption("width") - 2)

## Set-up the custom pager as the default pager

options(diffobj.pager=page.conf)
diffChr(1:200, 180:300)

## A blocking pager (this is effectively very similar to what `PagerBrowser`
## does); need to block b/c otherwise temp file with diff could be deleted
## before the device has a chance to read it since `browseURL` is not
## blocking itself.  On OS X we need to specify the extension so the correct
## program opens it (in this case `TextEdit`):

page.fun <- make_blocking(browseURL)
page.conf <- PagerSystem(pager=page.fun, file.ext="txt")
diffChr(1:200, 180:300, pager=page.conf)

## End(Not run)

Want to suggest features or report bugs for rdrr.io? Use the GitHub issue tracker.