Display, Edit, Re-evaluate and Save Past S-PLUS Expressions

DESCRIPTION:

Retrieves past S-PLUS expressions from the audit file, optionally restricting the search to those expressions matching a specified pattern. A single expression may be chosen from among those found. Expressions may be edited, evaluated, written to a file, or made into the body of a new function.

USAGE:

history(pattern, regexpr.pattern, max.expr=10, evaluate=T, 
        call=<<see below>>,  
        menu= missing("function") && missing(file), 
        graphics=F,  where=<<see below>>, editor=F, reverse=menu, 
        "function", file=T) 
again(pattern, regexpr.pattern, editor=F) 

OPTIONAL ARGUMENTS:

pattern
pattern to use in selecting expressions. This argument is now deprecated in favor of the regexpr.pattern argument. See also the call argument below.
regexpr.pattern
pattern to use in selecting expressions. Previously evaluated expressions are selected from the audit file if they match this pattern (as a regular expression in the sense of the awk language). By default, all patterns are matched. See also the call argument below.
max.expr
maximum number of expressions to select from the audit file, among those that match regexpr.pattern.
evaluate
logical flag: if evaluate=TRUE, the selected expression are evaluated. The default is TRUE unless the function argument is supplied.
call
call to match in selecting expressions. If this argument is given, the search is restricted to expressions containing function calls (that is, expressions containing the call pattern followed by a left parenthesis). If call is specified, regexpr.pattern is ignored. Because of this, other arguments like max.expr need to be given in the name=value form when call is specified. Otherwise, S-PLUS will match them to the regexpr.pattern argument.
menu
logical flag: if menu=TRUE, a menu of the selected expressions is presented, allowing one to be chosen. If menu=FALSE, the entire set of selected expressions is processed.
graphics
logical flag: if graphics=TRUE, graphics menus are used if available. A graphics device must be open and have menu capability for this option to work. See the function menu for more details.
where
location in which to find the audit file. By default, history looks in the current directory for the audit file. The where argument for history is similar to the one for the get function: it can be a numeric value specifying a position in the search list, or a character vector of length 1 specifying the name of the directory.
editor
function, character string, or logical flag describing how the selected expression(s) should be edited. If editor is a function (typically an editor function like ed or vi), the function is invoked on the history selection. If editor is a character string, it is assumed to be the name of a function. If editor=TRUE, the editor defined by editor=options()$editor is used. If editor=FALSE, the selected expressions will not be edited.
reverse
logical flag: if reverse=TRUE, the expressions are processed with the most recent ones listed first. Use reverse=FALSE for chronological order. The default value is the value of the menu argument.
function
character string specifying the name to assign to the function composed of the expressions matched by history. Typically you need to edit the function definition, so S-PLUS sends it to a file given by the file argument.
file
character string naming a file (or connection) on which to write the selected expression(s). If function="NAME" is supplied, for example, the default for file is "NAME.q". Expressions are written after any menu selection and editing has taken place; expressions are also written independently of whether evaluate=TRUE.

VALUE:

if evaluate=TRUE, the result obtained by evaluating the selected expression(s) is returned. Otherwise, the parsed but unevaluated expression list is invisibly returned.

SIDE EFFECTS:

If evaluate=TRUE, the selected expression(s) are evaluated. If file is given, the expression(s) are written to the named file.

DETAILS:

The history function looks backwards through the audit file, selecting the most recent max.expr expressions that match the regexpr.pattern or call patterns. If more than one expression is found and menu=TRUE, you are prompted to choose one of the expressions via the menu function. To choose none of them, type 0 instead of a selection number. If menu=FALSE, no choice is offered and the entire set is matched. In either case, the selected expression(s) are edited if editor=TRUE, then written to file if one is given. The expression(s) are then evaluated if evaluate=TRUE, and the value of the (last) expression is returned. If evaluate=FALSE, a parsed expression list is invisibly returned.

The function again re-evaluates the last matching expression. Typing again() is equivalent to typing history(max.expr=1). The value of the expression is printed even when it is an assignment.

You may also use the command line editing feature to recall previous commands in your session. To do this, start S-PLUS with the -e flag. See the Getting Started chapter in the User's Guide for more information.

WARNING:

The pattern argument is treated as an awk regular expression. This is important to know if your pattern includes parentheses, brackets, dollar signs, asterisks, etc., all of which have special meaning to awk. In general, you will be safe if you use alphabetic and numeric characters, with a period ( .) in place of any other single character.

SEE ALSO:

, , , , , .

EXAMPLES:

# display a menu of last 10 expressions
# and choose one to evaluate 
history() 
# choose one from the last 20 expressions
history(max.expr=20)  
# the most recent expressions containing word plot   
history("plot")    
history(plot) 
# re-evaluate the last call to plot   
history(call="plot", max.expr=1)  
history(call=plot, max.expr=1) 
# re-evaluate the last expression containing x, 
# but edit it first 
history(x, max.expr=1, editor=T) 
# print but do not evaluate recent calls to f 
history(call=f, eval=F, menu=F)   
# write the last 10 expressions in chronological 
# order to the file S.exprs
history(menu=F, eval=F, reverse=F, file="S.exprs") 
# re-evaluate the last expression   
again() 
# edit and re-evaluate the last expression
# and assign the result to value
value <- again(editor=T) 
# re-evaluate the last expression containing word plot    
again(plot) 
# invoke S-PLUS using command line editing  
Splus -e