source.pkg: Quickly load code and data of a package
In scriptests: Transcript-Based Unit Tests that are Easy to Create and Maintain

Description Usage Arguments Details Value Side effects Note Author(s) References See Also Examples

source() all of the source files and data files in a package into an environment on the search path. If an environment is not already attached by a previous invocation of source.pkg(), one will be created and attached. It also loads DLLs if requested, and if those DLLs can be found. This function is intended for use in code development, in situations where code from a package can be tested without worrying about imports, namespaces, etc.

source.pkg(pkg.dir = getOption("scriptests.pkg.dir", "pkg"),
           pattern = ".*",
           suffix = "\\.R$",
           dlls = c("no", "check", "build", "src"),
           unload=FALSE, pos = NA, all = FALSE,
           reset.function.envirs=TRUE,
           path=getOption("scriptests.pkg.path", default=getwd()),
           get.sccv=getOption('source.pkg.sccversion'))

`pkg.dir`	The directory where the package code lives. This is remembered and the same value used as the default in subsequent invocations. This can be different from the package name, which is read from `<pkg.dir>/DESCRIPTION`.
`pattern`	A regular expression specifying the R files to source
`suffix`	The suffix for the R code files. Files are sourced only if they match both `pattern` and `suffix`.
`dlls`	Indicates where to look for DLLs or shared-objects: `no`: don't load any DLLs `check`: look in `<pkg.dir>.Rcheck/<pkg.name>/libs` and `<pkg.name>.Rcheck/<pkg.name>/libs` `build`: look in the directory `build` (can be created with `R CMD INSTALL -l build <package-tarball>`, and before loading each time, it may be necessary to do `dyn.unload(...)`, using the path of the DLL as printed.)
`pos`	Which environment on the search path to source R code into
`unload`	Should compiled object files be unloaded?
`all`	If `TRUE`, all files matching the pattern and suffix are sourced, if `FALSE`, only files that have changed since last sourced are sourced again.
`reset.function.envirs`	If `TRUE` the environments on all functions sourced are set to the global environment. See NOTE below for explanation.
`path`	The file system path to the directory in which the package is located. Can be a semi-colon separated list of paths. The initial default for `path` is the current directory. By default, R source files are looked for in the directory found by appending `pkg.dir` to `path`, i.e. `<path>/<pkg.dir>/R/*.R`. If `path` contains the string `$PKG`, `pkg.dir` is substituted for `$PKG` instead of being appended to `path`. `path` is remembered and the same value used as the default in subsequent invocations.
`get.sccv`	The name of the program that outputs the source-code-control version number, e.g., for SVN, `svnversion`.

The package directory (pkg.dir) does not need to be the same as the package name. The package name (refered to here as pkg.name) is found by reading the DESCRIPTION file.

All the objects created by the .R files are created in a special environment named pkgcode:<pkg.name>. If this environment does not already exist, it will be created and attached to the search path in position pos. If it does exist, no attempt is made to clean it before sourcing the .R files. All functions and objects defined in the .R files will be visible – namespaces are not implemented.

The easiest way to use this function is when the working directory of the R session is the directory where each package lives, i.e., the R code for package mypackage will be in the directory ./mypackage/R (relative to the working directory of the R session.) However, if the package directory is located elsewhere, supply it as path=, and this will be remembered for future invocations of source.pkg().

This function does not attempt to replicate all the actions involved in creating and attaching a package. It does the following:

creates a environment named pkgcode:<pkg.name> where <pkg.name> is the name of the package (if it doesn't already exist)
looks for a Depends line in the DESCRIPTION file and loads specified packages
looks for .R files in the R subdirectory of the package, and, as appropriate, the R/windows or R/unix subdirectories, and uses sys.source() to read these into the pkgcode:<pkg.name> environment. If there is a Collate field in the DESCRIPTION files, this is used to sort the files before sourcing them.
looks for .Rdata and .rda files in the data subdirectory, and uses load() to read these into the pkgcode:<pkg.name> environment
if dlls=="check" (not the default), source.pkg() looks for DLLs (SO files under Unix) in the directory left by R CMD check <pkg.dir>, i.e., in <pkg.dir>.Rcheck/<pkg.name>/libs or <pkg.name>.Rcheck/<pkg.name>/libs, and uses dyn.load() to load these DLLs. If the DLL was already loaded (as indicated by getLoadedDLLs()), dyn.unload() is called first. Be aware that unloading and reloading a DLL is not a reliable operation under many OS's, and even when the call completes without apparent error, the R session can be corrupted.

This function is executed for its side effects, which may include attaching a new environment to the search path, or moving an existing one, and reading function and object definitions into that environment. source.pkg() returns as its value a list of the problems encountered when sourcing the files.

An environment is created and attached to the search path (or if it already exists, it is modified.) A variable named scriptests.pkg.dir is set in the global environment to the directory of the package whose code was sourced.

If reset.function.envirs=FALSE is supplied, the environments on the functions sourced will be the environment where they live on the search path. Functions with their environment set like this will not be able to see objects in the global environment or in any environment earlier on the search path. The default behavior of setting their environment to be the global environment produces behavior that is more similar to when the functions are sourced directly into the global environment.

Tony Plate tplate@acm.org

Similar ideas in an R-devel post by Barry Rowlingson: http://n4.nabble.com/Lightweight-package-idea-td924000.html#a924000 (link no longer active)
Hadley Wickham source_package() function http://gist.github.com/180883, reads DESCRIPTION, loads dependencies, respects collation order (link no longer active)

runtests() shares the options() variables scriptests.pkg.dir and scriptests.pkg.path that provide defaults for the pkg.dir and path arguments.

scriptests-package gives and overview of the package.

## Not run: 
# sourcing the code in a package stored in <mypackage>/{DESCRIPTION,R,man,tests}:
source.pkg("<mypackage>")
# sourcing the code in a package stored in path/to/dir/<mypackage>/{DESCRIPTION,R,man,tests}:
source.pkg("<mypackage>", path="path/to/dir")
# sourcing the code in a package stored in pkg/{DESCRIPTION,R,man,tests}:
# where "pkg" is unrelated to the name of the pacakage
source.pkg("pkg", path="path/to/dir")
# sourcing the code in a package stored in <mypackage>/pkg/{DESCRIPTION,R,man,tests}:
source.pkg("<mypackage>", path="$PKG/pkg")

## End(Not run)