John Chambers | 16 Jul 19:40 2010

Inserting and testing revised functions in a package

A new facility has been added to r-devel for experimenting by authors of 

The idea is to insert modified code from the package source into the 
running package without re-installing.  So one can change, test, change, 
etc in a quick loop.

The mechanism is to evaluate some files of source code, returning an 
environment object which is a snapshot of the code.  From this 
environment, functions and methods can be inserted into the environment 
of the package in the current session.  The insertion uses the trace() 
mechanism, so the original code can be restored.

The one-step version is:
   insertSource("mySourceFile.R", package = "myPackage", functions = "foo")

This is intended specially for those of us who own largish packages. (It 
proved useful in debugging itself, e.g.)  You can use the other trace() 
mechanisms with it, with a little care, as well as debug() etc.

For the moment it only works on functions and S4 methods, via trace().  
There are a number of possible future applications, both for 
insertSource and for the underlying snapshot environments as records of 
the state of the code.

The code was added today (revision 52545)  See ?insertSource for 
details, a piece of the documentation is at the end of this mail.



evalSource(source, package = "", lock = TRUE, cache = FALSE)

insertSource(source, package = "", functions = , methods = )


The |source| file is parsed and evaluated, suppressing by default the 
actual caching of method and class definitions contained in it, so that 
functions and methods can be tested out in a reversible way. The result, 
if all goes well, is an environment containing the assigned objects and 
metadata corresponding to method and class definitions in the source file.

 >From this environment, the objects are inserted into the package, into 
its namespace if it has one, for use during the current session or until 
reverting to the original version by a call to untrace(). The insertion 
is done by calls to the internal version of |trace()|, to make reversion 

Because the trace mechanism is used, only function-type objects will be 
inserted, functions themselves or S4 methods.

When the |functions| and |methods| arguments are both omitted, 
|insertSource| selects all suitable objects from the result of 
evaluating the |source| file.

In all cases, only objects in the source file that differ from the 
corresponding objects in the package are inserted. The definition of 
"differ" is that either the argument list (including default 
expressions) or the body of the function is not identical. Note that in 
the case of a method, there need be no specific method for the 
corresponding signature in the package: the comparison is made to the 
method that would be selected for that signature.

	[[alternative HTML version deleted]]