Modify use of pager behavior with pager configuration objects to use as the
pager argument to the
diff* methods or as
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.
1 2 3 4 5 6 7 8 9
additional arguments to pass on to
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.
integer(1L) number of lines of output that triggers the use
of the pager; negative values lead to using
character(1L) an extension to append to file name passed to
character(1L), only for
TRUE or FALSE, whether the pager supports ANSI escape sequences.
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).
There is a close relationship between pagers and
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
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
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
PagerOff: Turn off pager
PagerSystem: Use the system pager as invoked by
PagerSystem, but provides
additional configuration options if the system pager is
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
getOption("viewer") if defined, or
browseURL if not
Important: Make sure you instantiate the pager objects with the
constructor functions (e.g.
new('PagerSystemLess', ...) rather than with
new as otherwise
they will not be properly configured.
The default configuration for
leads to output being sent to the pager if it exceeds the estimated window
PagerBrowser always sends output to the pager. This
behavior can be configured via the
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
sorts, except it does not appear to read the
$LESS system variable.
Should you configure your system pager to be the
more version of
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
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
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
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
otherwise the temporary file that contains the diff may be deleted before
the pager has a chance to read it.
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)