[Rd] Inserting and testing revised functions in a package

From: John Chambers <jmc_at_r-project.org>
Date: Fri, 16 Jul 2010 10:40:24 -0700


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

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.

Cheers,

   John

      Usage

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

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

      Details

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 possible.

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]]



R-devel_at_r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Fri 16 Jul 2010 - 17:42:48 GMT

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Sat 17 Jul 2010 - 06:10:17 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-devel. Please read the posting guide before posting to the list.

list of date sections of archive