| % File src/library/methods/man/evalSource.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 2010-2 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{evalSource} |
| \alias{evalSource} |
| \alias{insertSource} |
| \alias{sourceEnvironment-class} |
| \title{ |
| Use Function Definitions from a Source File without Reinstalling a Package |
| } |
| \description{ |
| Definitions of functions and/or methods from a source file are |
| inserted into a package, using the \code{\link{trace}} mechanism. |
| Typically, this allows testing or debugging modified versions of a few |
| functions without reinstalling a large package. |
| } |
| \usage{ |
| evalSource(source, package = "", lock = TRUE, cache = FALSE) |
| |
| insertSource(source, package = "", functions = , methods = , |
| force = ) |
| |
| } |
| \arguments{ |
| \item{source}{ |
| A file to be parsed and evaluated by \code{evalSource} to find the new |
| function and method definitions. |
| |
| The argument to \code{insertSource} can be an object of class \code{"sourceEnvironment"} |
| returned from a previous call |
| to \code{evalSource} If a file name is passed to \code{insertSource} |
| it calls \code{evalSource} to obtain the corresponding object. See |
| the section on the class for details. |
| |
| } |
| \item{package}{ |
| Optionally, the name of the package to which the new code corresponds |
| and into which it will be |
| inserted. Although the computations will attempt to infer the package |
| if it is omitted, the safe approach is to supply it. In the case of a |
| package that is not attached to the search list, the package name must |
| be supplied. |
| } |
| \item{functions, methods}{ |
| Optionally, the character-string names of the functions to be |
| used in the insertion. Names supplied in the \code{functions} |
| argument are expected to be defined as functions in the source. |
| For names supplied in the \code{methods} argument, a table of methods |
| is expected (as generated by calls to \code{\link{setMethod}}, see the |
| details section); methods from this table will be inserted by |
| \code{insertSource}. In both cases, the revised function or method is |
| inserted only if it differs from the version in the corresponding |
| package as loaded. |
| |
| If \code{what} is omitted, the results of evaluating the source file |
| will be compared to the contents of the package (see the details section). |
| } |
| \item{lock, cache}{ |
| Optional arguments to control the actions taken by \code{evalSource}. |
| If \code{lock} is \code{TRUE}, the environment in the object returned |
| will be locked, and so will all its bindings. |
| If \code{cache} is \code{FALSE}, the normal caching of method and |
| class definitions will be suppressed during evaluation of the |
| \code{source} file. |
| |
| The default settings are generally recommended, the \code{lock} to |
| support the credibility of the object returned as a snapshot of the |
| source file, and the second so that method definitions can be inserted |
| later by \code{insertSource} using the trace mechanism. |
| } |
| \item{force}{ |
| If \code{FALSE}, only functions currently in the environment will be |
| redefined, using \code{\link{trace}}. If \code{TRUE}, other |
| objects/functions will be simply assigned. By default, \code{TRUE} if |
| neither the \code{functions} nor the \code{methods} argument is supplied. |
| } |
| |
| } |
| \details{ |
| The \code{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 |
| \code{\link{untrace}}. |
| The insertion is done by calls to the internal version of |
| \code{\link{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 \code{functions} and \code{methods} arguments are both |
| omitted, \code{insertSource} selects all suitable objects from the |
| result of evaluating the \code{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 \dQuote{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. |
| |
| Nothing in the computation requires that the source file supplied be |
| the same file as in the original package source, although that case is |
| both likely and sensible if one is revising the package. Nothing in |
| the computations compares source files: the objects generated by |
| evaluating \code{source} are compared as objects to the content of the package. |
| } |
| \value{ |
| An object from class \code{"sourceEnvironment"}, a subclass of |
| \code{"environment"} (see the section on the class) |
| The environment contains the versions |
| of \emph{all} object resulting from evaluation of the source file. |
| The class also has slots for the time of creation, the source file |
| and the package name. |
| Future extensions may use these objects for versioning or other code tools. |
| |
| |
| The object returned can be used in debugging (see the section on that |
| topic) or as the \code{source} |
| argument in a future call to \code{insertSource}. If only some of the |
| revised functions were inserted in the first call, others can be |
| inserted in a later call without re-evaluating the source file, by |
| supplying the environment and optionally suitable \code{functions} |
| and/or \code{methods} argument. |
| } |
| |
| \section{Debugging}{ |
| Once a function or method has been inserted into a package by |
| \code{insertSource}, it can be studied by the standard debugging tools; |
| for example, \code{\link{debug}} or the various versions of |
| \code{\link{trace}}. |
| |
| Calls to \code{\link{trace}} should take the extra argument \code{edit |
| = env}, where \code{env} is the value returned by the call to |
| \code{evalSource}. |
| The trace mechanism has been used to install the revised version from |
| the source file, and supplying the argument ensures that it is this |
| version, not the original, that will be traced. See the example |
| below. |
| |
| To turn tracing off, but retain the source version, use \code{trace(x, |
| edit = env)} as in the example. To return to the original version |
| from the package, use \code{untrace(x)}. |
| } |
| |
| \section{Class \code{"sourceEnvironment"}}{ |
| Objects from this class can be treated as environments, to extract the |
| version of functions and methods generated by \code{evalSource}. |
| The objects also have the following slots: |
| \describe{ |
| \item{\code{packageName}:}{ The character-string name of the package |
| to which the source code corresponds. |
| } |
| \item{\code{dateCreated}:}{ The date and time that the source file was |
| evaluated (usually from a call to \code{\link{Sys.time}}). |
| } |
| \item{\code{sourceFile}:}{ The character-string name of the source file |
| used. |
| } |
| Note that using the environment does not change the \code{dateCreated}. |
| } |
| } |
| |
| \seealso{ |
| \code{\link{trace}} for the underlying mechanism, and also for the |
| \code{edit=} argument that can be used for somewhat similar purposes; |
| that function and also \code{\link{debug}} and |
| \code{\link{setBreakpoint}}, for techniques more oriented to |
| traditional debugging styles. |
| The present function is directly intended for the case that one is |
| modifying some of the source for an existing package, although it can |
| be used as well by inserting debugging code in the source (more useful |
| if the debugging involved is non-trivial). As noted in the details |
| section, the source |
| file need not be the same one in the original package source. |
| } |
| \examples{ |
| \dontrun{ |
| ## Suppose package P0 has a source file "all.R" |
| ## First, evaluate the source, and from it |
| ## insert the revised version of methods for summary() |
| env <- insertSource("./P0/R/all.R", package = "P0", |
| methods = "summary") |
| ## now test one of the methods, tracing the version from the source |
| trace("summary", signature = "myMat", browser, edit = env) |
| ## After testing, remove the browser() call but keep the source |
| trace("summary", signature = "myMat", edit = env) |
| ## Now insert all the (other) revised functions and methods |
| ## without re-evaluating the source file. |
| ## The package name is included in the object env. |
| insertSource(env) |
| } |
| } |
| \keyword{ programming } |
| \keyword{methods } |