Merge pull request #32 from databio/dev

Release PR for v 0.4.0

.Rbuildignore

@@ -3,4 +3,6 @@
 ^\.travis\.yml$
 ^cran-comments.md$
 ^CONDUCT\.md$
-^paper$
+^paper$
+.github
+^_pkgdown\.yaml$

.github/CONTRIBUTING.md

@@ -0,0 +1,20 @@
+# CONTRIBUTING #
+
+### Please contribute!
+
+We love collaboration.
+
+### Bugs?
+
+* Submit an issue on the [Issues page](https://github.com/databio/simpleCache/issues)
+
+### Code contributions
+
+* Fork this repo to your Github account
+* Clone your version on your account down to your machine from your account, e.g,. `git clone https://github.com/databio/simpleCache.git`
+* Make sure to track progress upstream (i.e., on our version of `simpleCache` at `databio/simpleCache`) by doing `git remote add upstream https://github.com/databio/simpleCache.git`. Before making changes make sure to pull changes in from upstream by doing either `git fetch upstream` then merge later or `git pull upstream` to fetch and merge in one step
+* Make your changes (bonus points for making changes on a new feature branch)
+* Push up to your account
+* Submit a pull request to home base (likely master branch, but check to make sure) at `databio/simpleCache`
+
+### Thanks for contributing!

.github/issue_template.md

@@ -0,0 +1,8 @@
+<!-- If this issue relates to usage of the package, whether a question, bug or similar, along with your query, please paste your devtools::session_info() or sessionInfo() into the code block below, AND include a reproducible example. If not, delete all this and proceed :) -->
+
+<details> <summary><strong>Session Info</strong></summary>
+
+```r
+
+```
+</details>

.github/pull_request_template.md

@@ -0,0 +1,16 @@
+<!--- Provide a general summary of your changes in the Title above -->
+
+## Description
+<!--- Describe your changes in detail -->
+
+## Related Issue
+<!--- if this closes an issue make sure include e.g., "fix #4"
+or similar - or if just relates to an issue make sure to mention
+it like "#4" -->
+
+## Example
+<!--- if introducing a new feature or changing behavior of existing
+methods/functions, include an example if possible to do in brief form -->
+
+<!--- Did you remember to include tests? Unless you're just changing
+grammar, please include new tests for your change -->

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: simpleCache
-Version: 0.3.1
+Version: 0.4.0
 Date: 2017-08-21
 Title: Simply Caching R Objects
 Description: Provides intuitive functions for caching R objects, encouraging
@@ -13,14 +13,13 @@ Description: Provides intuitive functions for caching R objects, encouraging
 Authors@R: c(person("VP", "Nagraj", email = "[email protected]", role =
     c("aut")), person("Nathan", "Sheffield", email = "[email protected]",
     role = c("aut", "cre")))
-Maintainer: Nathan Sheffield <[email protected]>
 Suggests:
     knitr,
     testthat
 Enhances: batchtools
 VignetteBuilder: knitr
 License: BSD_2_clause + file LICENSE
 Encoding: UTF-8
-URL: http://www.github.com/databio/simpleCache
-BugReports: http://www.github.com/databio/simpleCache
+URL: https://www.github.com/databio/simpleCache
+BugReports: https://www.github.com/databio/simpleCache
 RoxygenNote: 6.0.1.9000

NAMESPACE

@@ -10,7 +10,7 @@ export(setCacheDir)
 export(setSharedCacheDir)
 export(simpleCache)
 export(simpleCacheGlobal)
+export(simpleCacheOptions)
 export(simpleCacheShared)
 export(simpleCacheSharedGlobal)
 export(storeCache)
-export(viewCacheDirs)

NEWS

@@ -1,17 +1,31 @@
 # Change log
 All notable changes to this project will be documented in this file.
 
+## [0.4.0] -- Unreleased
+
+	- adds a lifespan arg to simpleCache() to create auto-expiring caches
+	- remove unnecessary parse argument to simpleCache()
+	- viewCacheDirs() renamed to simpleCacheOptions()
+
+## [0.3.1] -- 2017-08-21
+
+	- fixed a bug in unit tests that left behind a test cache in user home dir.
+	- changes cache building to happen in parent.frame()
+	- repaired vignette so R code is displayed properly
+	- added deleteCaches() function and docs
+	- reduced size of unit test cache for speed increase
+
 ## [0.3.0] -- 2017-08-21
 
-	- Switched default cache dir to tempdir()
+	- switched default cache dir to tempdir()
 	- changed availCaches() to listCaches()
-	- changes cache building to happen in parent.frame(), so that any loaded
+	- changes cache building to happen in globalenv(), so that any loaded
 	  packages are available for cache building
 
 
 ## [0.2.1] -- 2017-07-30
 
-	- Added examples
+	- added examples
 
 ## [0.2.0] -- 2017-07-30
 
@@ -20,4 +34,4 @@ All notable changes to this project will be documented in this file.
 
 ## [0.0.1]
 
-	- Long-term stable version
+	- long-term stable version

R/cacheDirectories.R

@@ -6,7 +6,7 @@
 # caches.
 
 #' Sets a global variable specifying the default cache directory for
-#' simpleCache() calls.
+#' \code{\link{simpleCache}} calls.
 #'
 #' @param cacheDir Directory where caches should be stored
 #' @export
@@ -19,7 +19,7 @@ setCacheDir = function(cacheDir) {
 #' Set shared cache directory
 #'
 #' Sets global variable specifying the default cache directory for
-#' simpleCacheShared() calls; this function is simply a helper alias for caching
+#' \code{\link{simpleCacheShared}} calls; this function is simply a helper alias for caching
 #' results that will be used across projects.
 #'
 #' @param sharedCacheDir Directory where shared caches should be stored
@@ -36,11 +36,11 @@ setCacheBuildDir = function(cacheBuildDir) {
 	options(RBUILD.DIR=cacheBuildDir)
 }
 
-#' View cache directories
+#' View simpleCache options
 #'
-#' Views cache directory global variables
+#' Views simpleCache global variables
 #' @export
-viewCacheDirs = function() {
+simpleCacheOptions = function() {
 	message("RESOURCES.RCACHE:\t", getOption("RESOURCES.RCACHE"))
 	message("RCACHE.DIR:\t", getOption("RCACHE.DIR"))
 	message("RBUILD.DIR:\t", getOption("RBUILD.DIR"))
@@ -59,7 +59,7 @@ addCacheSearchEnvironment = function(addEnv) {
 	options(SIMPLECACHE.ENV=append(addEnv, getOption("SIMPLECACHE.ENV")))
 }
 
-#' Sets global option of cache search environments to NULL.
+#' Sets global option of cache search environments to \code{NULL}.
 #' 
 #' @export
 resetCacheSearchEnvironment = function() {

R/loadCaches.R

@@ -4,15 +4,17 @@
 #' for stuff you already cached previously, so it won't build any caches.
 #'
 #' @param cacheNames Vector of caches to load.
+#' @param loadEnvir Environment into which to load each cache.
 #' @param ... Additional parameters passed to simpleCache.
 #' @export
 #' @example
 #' R/examples/example.R
-loadCaches = function(cacheNames, ...) {
+loadCaches = function(cacheNames, loadEnvir=NULL, ...) {
+  if (is.null(loadEnvir)) { loadEnvir = parent.frame(n=2) }
 	for (i in 1:length(cacheNames)) {
 		# By default, load these caches into the environment that
 		# calls loadCaches (which is the grandparent, n=2, of the call to	
 		# simpleCache.
-		simpleCache(cacheNames[i], loadEnvir=parent.frame(n=2), ...)
+		simpleCache(cacheNames[i], loadEnvir=loadEnvir, ...)
 	}
 }

R/sharedCaches.R

@@ -8,7 +8,7 @@
 #' (instead of the typical default PROJECT directory)
 
 #' 
-#' @param ... Parameters passed to simpleCache().
+#' @param ... Parameters passed to \code{\link{simpleCache}}.
 #' @export
 simpleCacheShared = function(...) {
 	# Since this is a function calling this, I have to set the loadEnvir here,
@@ -22,15 +22,15 @@ simpleCacheShared = function(...) {
 #' simpleCache normally loads variables into the calling environment; this
 #' ensures that the variables are loaded in the global environment.
 #'
-#' @param ... Parameters passed to simpleCache().
+#' @param ... Parameters passed to \code{\link{simpleCache}}.
 #' @export
 simpleCacheGlobal = function(...) {
 	simpleCache(..., loadEnvir=globalenv())
 }
 
 #' Helper alias for loading shared caches into the global environment.
 #' 
-#' @param ... Parameters passed to simpleCache().
+#' @param ... Parameters passed to \code{\link{simpleCache}}.
 #' @export
 simpleCacheSharedGlobal = function(...) {
 	simpleCache(..., cacheDir=getOption("RESOURCES.RCACHE"), loadEnvir=globalenv())

R/simpleCache.R

@@ -1,15 +1,12 @@
 ## Package documentation
 #' Provides intuitive functions for caching R objects, encouraging faster
 #' reproducible and restartable R analysis
-#'
-#' simpleCache provides a function (simpleCache())
 #' 
-#' @references \url{https://github.com/nsheff/}
-## @import if you import any packages; here.
+#' @references \url{https://github.com/databio/simpleCache}
 #' @docType package
-#' @name simpleCache
 #' @author Nathan Sheffield
-NULL
+#' @aliases simpleCache-package
+"_PACKAGE"
 
 ################################################################################
 
@@ -23,10 +20,10 @@ NULL
 #' troubles if you misuse the caching system. The object should be considered
 #' static. 
 #' 
-#' You should pass a bracketed R code snippet like `{ rnorm(500) }` as the
+#' You should pass a bracketed R code snippet like \code{rnorm(500)} as the
 #' instruction, and simpleCache will create the object. Alternatively, if the
 #' code to create the cache is large, you can put an R script called object.R in
-#' the RBUILD.DIR (the name of the file *must* match the name of the object it
+#' the \code{\link[=setCacheBuildDir]{RBUILD.DIR}} (the name of the file *must* match the name of the object it
 #' creates *exactly*). If you don't provide an instruction, the function sources
 
 #' RBUILD.DIR/object.R and caches the result as the object. This source file
@@ -41,46 +38,50 @@ NULL
 #' environment variables you use in your instruction code. You can use this
 #' using the parameter buildEnvir (just provide a list of named variables).
 #' 
-#' @param cacheName	Unique name for the cache. Be careful.
-#' @param instruction  Quoted R code to be evaluated. The returned value of this
+#' @param cacheName	A character vector for a unique name for the cache. Be careful.
+#' @param instruction  R expression (in braces) to be evaluated. The returned value of this
 #'     code is what will be cached under the cacheName.
-#' @param buildEnvir   You may choose to provide additional variables necessary
-#'     for evaluating the code in instruction.
-#' @param reload   forces re-loading the cache, even if it exists in the env.
-#' @param recreate forces reconstruction of the cache
-#' @param noload   noload is useful for: you want to create the caches, but not
-#'     load them if they aren't there (like a cache creation loop).
-#' @param cacheDir The directory where caches are saved (and loaded from).
-#'			Defaults to the global RCACHE.DIR variable
-#' @param cacheSubDir You can specify a subdirectory within the cacheDir
-#' 			variable. Defaults to NULL.
-#' @param assignToVariable By default, simpleCache assigns the cache to a
-#'     variable named cacheName; you can overrule that here.
-#' @param loadEnvir    Into which environment would you like to load the
-#'     variable? Defaults to parent.frame.
+#' @param buildEnvir   An environment (or list) providing additional variables
+#'     necessary for evaluating the code in instruction.
+#' @param reload   Logical indicating whether to force re-loading the cache,
+#'     even if it exists in the env.
+#' @param recreate Logical indicating whether to force reconstruction of the
+#'     cache
+#' @param noload   Logical indicating whether to create but not load the cache.
+#'     noload is useful for: you want to create the caches, but not load (like a
+#'     cache creation loop).
+#' @param cacheDir Character vector specifying the directory where caches are
+#'			saved (and loaded from). Defaults to the variable set by
+#'			\code{\link[=setCacheDir]{setCacheDir()}}.
+#' @param cacheSubDir Character vector specifying a subdirectory within the
+#' 			\code{cacheDir} variable. Defaults to \code{NULL}.
+#' @param assignToVariable Character vector for a variable name to load the
+#'     cache into. By default, \code{simpleCache} assigns the cache to a
+#'     variable named \code{cacheName}; you can overrule that here.
+#' @param loadEnvir    An environment. Into which environment would you like to
+#'     load the variable? Defaults to \code{\link[base]{parent.frame}}.
 #' @param searchEnvir  a vector of environments to search for the already loaded
 #'     cache.
-#' @param timer Report how long it took to create the cache?
+#' @param timer Logical indicating whether to report how long it took to create
+#'     the cache.
 #' @param buildDir Location of Build files (files with instructions for use If
 #'		the instructions argument is not provided). Defaults to RBUILD.DIR
 #'		global option.
-#' @param parse By default, simpleCache will guess whether you want to parse the
-#'     instruction, based on whether it is quoted. You can overwrite the guess
-#'     with this parameter; but this may disappear in the future. In general,
-#'     you should note quote, but use {} around your instructions.
 #' @param nofail By default, simpleCache throws an error if the instructions
 #'     fail. Use this option to convert this error into a warning. No cache will
 #'     be created, but simpleCache will not then hard-stop your processing. This
-#'     is useful, for example, if you are creating a bunch of caches and it's ok
-#'     if some of them do not complete.
-#' @param batchRegistry A batchtools registry object (built with
-#'     batchtools::makeRegistry()). If provided, this cache will be created on
+#'     is useful, for example, if you are creating a bunch of caches (for
+#'     example using \code{lapply}) and it's ok if some of them do not complete.
+#' @param batchRegistry A \code{batchtools} registry object (built with
+#'      \code{\link[batchtools]{makeRegistry}}). If provided, this cache will be created on
 #'     the cluster using your batchtools configuration
 #' @param batchResources A list of variables to provide to batchtools for
-#'     cluster resource managers. Used as the `res` argument to
-#'     batchtools::batchMap()
+#'     cluster resource managers. Used as the \code{res} argument to
+#'     \code{\link[batchtools]{batchMap}}
+#' @param lifespan Numeric specifying the maximum age of cache, in days, to
+#'                 allow before automatically triggering \code{recreate=TRUE}.
 #' @param pepSettings Experimental untested feature.
-#' @param  ignoreLock   internal parameter used for batch job submission; don't
+#' @param ignoreLock Internal parameter used for batch job submission; don't
 #'     touch.
 #' @export
 #' @example
@@ -90,38 +91,32 @@ simpleCache = function(cacheName, instruction=NULL, buildEnvir=NULL,
 	cacheDir=getOption("RCACHE.DIR"), cacheSubDir=NULL, timer=FALSE,
 	buildDir=getOption("RBUILD.DIR"), assignToVariable=NULL,
 	loadEnvir=parent.frame(), searchEnvir=getOption("SIMPLECACHE.ENV"),
-	parse=NULL, nofail=FALSE, batchRegistry=NULL,
-	batchResources=NULL, pepSettings=NULL, ignoreLock=FALSE) {
+	nofail=FALSE, batchRegistry=NULL, batchResources=NULL, pepSettings=NULL, 
+	ignoreLock=FALSE, lifespan=NULL) {
+
+	if (!"character" %in% class(cacheName)) {
+		stop("simpleCache expects the cacheName variable to be a character vector.")
+	}
 
 	# Because R evaluates arguments lazily (only when they are used),
 	# it will not evaluate the instruction if I first wrap it in a
 	# primitive substitute call. Then I can evaluate conditionally
 	# (if the cache needs to be recreated)
 	instruction = substitute(instruction)
-	if (is.null(parse)) {
-		if ("character" %in% class(instruction)) {
-
-			parse = TRUE
-			warning(strwrap("Detected a character instruction; consider wrapping
-			in {} instead of quotes."))
-		} else {
-			parse = FALSE
-		}
-	}
-	if (!is.null(cacheSubDir)) {
-		cacheDir = file.path(cacheDir, cacheSubDir)
-	}
+	if ("character" %in% class(instruction)) {
+		message("Character instruction; consider wrapping in braces.")
+		parse = TRUE
+	} else { parse = FALSE }
+
+	# Handle directory paths.
+	if (!is.null(cacheSubDir)) { cacheDir = file.path(cacheDir, cacheSubDir) }
 	if (is.null(cacheDir)) {
 		message(strwrap("No cacheDir specified. You should set global option
 		RCACHE.DIR with setCacheDir(), or specify a cacheDir parameter directly
 		to simpleCache(). With no other option, simpleCache will use tempdir():
 		", initial="", prefix=" "), tempdir())
 		cacheDir = tempdir()
 	}
-	if (!"character" %in% class(cacheName)) {
-		stop("simpleCache expects the cacheName variable to be a character
-		vector.")
-	}
 
 	if (!file.exists(cacheDir)) {
 		dir.create(cacheDir, recursive=TRUE)
@@ -149,6 +144,12 @@ simpleCache = function(cacheName, instruction=NULL, buildEnvir=NULL,
 
 	ret = NULL # The default, in case the cache construction fails.
 
+	if (.tooOld(cacheFile, lifespan)) {
+		message(sprintf(
+			"Stale cache: '%s' (age > %d day(s))", cacheFile, lifespan))
+		recreate = TRUE
+	}
+
 	if(cacheExists & !reload & !recreate) {
 		message("::Object exists (in ", cacheWhere, ")::\t", cacheName)
 		#return(get(cacheName))