track (version 1.1.9)

track.history: Functions for incrementally writing command history to a file.

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

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.

Value

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

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:

if (interactive()) {
    track.history.load()
    track.history.start()
}
    

See Also

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

Examples

Run this code
## Not run: 
# ## Can't use history except in Rgui and Rterm
# track.history.start()
# ## End(Not run)

Run the code above in your browser using DataLab