Functions for incrementally writing command history to a file.

Share:

Description

These functions provide the ability to append recent commands to a history file after (almost) every top level command. This makes it unnecessary to use savehistory() and solves the problem of command history not being saved on accidental or abnormal termination of an R session.

Usage

1
2
3
4
5
6
track.history.start(file = NULL, width = NULL, style = NULL, times =
  NULL, load = TRUE, verbose = FALSE, message="Session start")
track.history.stop()
track.history.status()
track.history.load(times = FALSE)
track.history.writer(expr, value, ok, visible)

Arguments

file

File to store the incremental history in. Defaults to .Rincr_history.

width

Width to use deparsing for fast-style history saving. Defaults to 120.

style

Two styles are possible:

  • full: (default) Use the internal R history mechanism. This is slower, but it records everything typed at the command prompt, in the original formatting.

  • fast: Use deparsed version of the most recently executed command. This is fast, but it doesn't record comments and some commands with errors, and it changes formatting.

times

Should time stamps be written to or read from the file? The default behavior for track.history.start() is TRUE. The default when loading history is FALSE, so that time stamps do not appear in the interactive history.

load

Should existing history be loaded when starting incremental history?

verbose

Should comments be printed?

expr

Provided by the task callback

value

Provided by the task callback

ok

Provided by the task callback

visible

Provided by the task callback

message

A string to be written (once) to the incremental history file along with the date and time when incremental history tracking is started.

Details

Default values are taken first from options incr.hist.style, incr.hist.width, incr.hist.file and incr.hist.times. If those option values don't exist, values are taken from environment variables R_INCR_HIST_STYLE, R_INCR_HIST_WIDTH, R_INCR_HIST_FILE, R_INCR_HIST_TIMES.

  • track.history.start() installs track.history.writer() as a task callback handler.

  • track.history.load() loads history from the file that incremental history is being written to.

  • track.history.stop() removes the task callback handler.

  • track.history.writer() is the task callback handler – it is not intended to be called by the user.

If arguments are supplied to track.history.start(), their values are remembered in options() and used for the remainder of the session or until changed.

The history stored using style="full" is more complete and accurate, in that it includes comments, unparseable commands, and original formatting. It is somewhat slower because it is based on the internal history mechanism, which doesn't provide an easy way of identifying which are the new commands. Consequently, when using style="full" track.history.writer() must inspect the entire internal history at the end of each command to work out which lines in it have been added since the last time history was written. However, the time difference seems negligible for interactive use on ordinary workstations circa 2010.

To set up incremental history tracking automatically, put the following in your .Rprofile:

1
2
3
4
5

Value

track.history.status() returns a character string: "on" or "off". The other functions currently provide no useful return values.

Author(s)

Tony Plate tplate@acm.org

See Also

addTaskCallback To read in command history that is stored in a particular file, use loadhistory(file). savehistory

Examples

1
2
3
4
5
## Not run: 
## Can't use history except in Rgui and Rterm
track.history.start()

## End(Not run)