% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/DBI.R
\name{createCache}
\alias{createCache}
\alias{loadFromCache}
\alias{extractFromCache}
\alias{rmFromCache}
\alias{CacheDBFile}
\alias{CacheStorageDir}
\alias{CacheStoredFile}
\alias{CacheDBTableName}
\alias{CacheIsACache}
\title{Low-level functions to create and work with a cache}
\usage{
createCache(
  cachePath = getOption("reproducible.cachePath"),
  drv = getDrv(getOption("reproducible.drv", NULL)),
  conn = getOption("reproducible.conn", NULL),
  force = FALSE,
  verbose = getOption("reproducible.verbose")
)

loadFromCache(
  cachePath = getOption("reproducible.cachePath"),
  cacheId,
  preDigest,
  fullCacheTableForObj = NULL,
  cacheSaveFormat = getOption("reproducible.cacheSaveFormat", .rdsFormat),
  .functionName = NULL,
  .dotsFromCache = NULL,
  drv = getDrv(getOption("reproducible.drv", NULL)),
  conn = getOption("reproducible.conn", NULL),
  verbose = getOption("reproducible.verbose")
)

extractFromCache(sc, elem, ifNot = NULL)

rmFromCache(
  cachePath = getOption("reproducible.cachePath"),
  cacheId,
  drv = getDrv(getOption("reproducible.drv", NULL)),
  conn = getOption("reproducible.conn", NULL),
  cacheSaveFormat = getOption("reproducible.cacheSaveFormat", .rdsFormat),
  verbose = getOption("reproducible.verbose"),
  ...
)

CacheDBFile(
  cachePath = getOption("reproducible.cachePath"),
  drv = getDrv(getOption("reproducible.drv", NULL)),
  conn = getOption("reproducible.conn", NULL)
)

CacheStorageDir(cachePath = getOption("reproducible.cachePath"))

CacheStoredFile(
  cachePath = getOption("reproducible.cachePath"),
  cacheId,
  cacheSaveFormat = getOption("reproducible.cacheSaveFormat"),
  obj = NULL,
  readOnly = FALSE
)

CacheDBTableName(
  cachePath = getOption("reproducible.cachePath"),
  drv = getDrv(getOption("reproducible.drv", NULL))
)

CacheIsACache(
  cachePath = getOption("reproducible.cachePath"),
  create = FALSE,
  drv = getDrv(getOption("reproducible.drv", NULL)),
  conn = getOption("reproducible.conn", NULL),
  verbose = getOption("reproducible.verbose")
)
}
\arguments{
\item{cachePath}{A path describing the directory in which to create
the database file(s)}

\item{drv}{A driver, passed to \code{dbConnect}}

\item{conn}{an optional \code{DBIConnection} object, as returned by \code{dbConnect()}.}

\item{force}{Logical. Should it create a cache in the \code{cachePath},
even if it already exists, overwriting.}

\item{verbose}{Numeric, -1 silent (where possible), 0 being very quiet,
1 showing more messaging, 2 being more messaging, etc.
Default is 1. Above 3 will output much more information about the internals of
Caching, which may help diagnose Caching challenges. Can set globally with an
option, e.g., \verb{options('reproducible.verbose' = 0) to reduce to minimal}}

\item{cacheId}{The cacheId or otherwise digested hash value, as character string.}

\item{preDigest}{The list of \code{preDigest} that comes from \code{CacheDigest} of an object}

\item{fullCacheTableForObj}{The result of \code{showCache}, but subsetted for only
the \code{cacheId} being loaded or selected}

\item{cacheSaveFormat}{The text string representing the file extension used normally by
different save formats; currently only \code{"rds"} or \code{"qs"} (which now uses \code{qs2} package.
Defaults to \code{getOption("reproducible.cacheSaveFormat", "rds")}}

\item{.functionName}{Optional. Used for messaging when this function is called from \code{Cache}}

\item{.dotsFromCache}{Optional. Used internally.}

\item{sc}{a cache tags \code{data.table} object}

\item{elem}{character string specifying a \code{tagKey} value to match}

\item{ifNot}{character (or NULL) specifying the return value to use if \code{elem} not matched}

\item{...}{Arguments passed to \code{FUN}, if \code{FUN} is not an expression.}

\item{obj}{The optional object that is of interest; it may have an attribute "saveRawFile"
that would be important.}

\item{readOnly}{Logical. Only relevant during transition from \code{qs} to \code{qs2}.
Essentially, during transition, \code{qs} objects can be read, but not saved.
If \code{TRUE} then the \code{CacheStoredFile} can return a \code{.qs} file; if \code{FALSE},
then this will not be able to return \code{qs}; instead it will return \code{qs2}
files.}

\item{create}{Logical. Currently only affects non \pkg{RSQLite} default drivers.
If \code{TRUE} and there is no Cache database, the function will create one.}
}
\value{
\itemize{
\item \code{createCache()} returns \code{NULL} (invisibly) and intended to be called for side effects;
}

\itemize{
\item \code{loadFromCache()} returns the object from the cache that has the particular \code{cacheId};
}

\itemize{
\item \code{extractFromCache()} returns the \code{tagValue} from the cache corresponding to \code{elem} if found,
otherwise the value of \code{ifNot};
}

\itemize{
\item \code{rmFromCache()} returns \code{NULL} (invisibly) and is intended to be called for side effects;
}

\itemize{
\item \code{CacheDBFile()} returns the name of the database file for a given Cache,
when \code{useDBI() == FALSE}, or \code{NULL} if \code{TRUE};
\item \code{CacheDBFiles()} (i.e,. plural) returns the name of all the database files for
a given Cache when \code{useDBI() == TRUE}, or \code{NULL} if \code{FALSE};
\item \code{CacheStoredFile()} returns the file path to the file with the specified hash value,
This can be loaded to memory with e.g., \code{\link[=loadFile]{loadFile()}}.;
}

\itemize{
\item \code{CacheStorageDir()} returns the name of the directory where cached objects are stored;
}

\itemize{
\item \code{CacheStoredFile} returns the file path to the file with the specified hash value;
}

\itemize{
\item \code{CacheDBTableName()} returns the name of the table inside the SQL database, if that
is being used;
}

\itemize{
\item \code{CacheIsACache()} returns a logical indicating whether the \code{cachePath} is currently
a \code{reproducible} cache database;
}
}
\description{
\strong{These are intended for advanced use only.}
}
\details{
\itemize{
\item \code{createCache()} will create a Cache folder structure and necessary files, based on
the particular \code{drv} or \code{conn} provided;
}

\itemize{
\item \code{loadFromCache()} retrieves a single object from the cache, given its \code{cacheId};
}

\itemize{
\item \code{extractFromCache()} retrieves a single \code{tagValue} from the cache based on
the \code{tagKey} of \code{elem};
}

\itemize{
\item \code{rmFromCache()} removes one or more items from the cache, and updates the cache
database files.
}
}
\examples{
data.table::setDTthreads(2)
newCache <- tempdir2()
createCache(newCache)

out <- Cache(rnorm(1), cachePath = newCache)
cacheId <- gsub("cacheId:", "", attr(out, "tags"))
loadFromCache(newCache, cacheId = cacheId)

rmFromCache(newCache, cacheId = cacheId)

# clean up
unlink(newCache, recursive = TRUE)

data.table::setDTthreads(2)
newCache <- tempdir2()

# Given the drv and conn, creates the minimum infrastructure for a cache
createCache(newCache)

CacheDBFile(newCache) # identifies the database file
CacheStorageDir(newCache) # identifies the directory where cached objects are stored

out <- Cache(rnorm(1), cachePath = newCache)
cacheId <- gsub("cacheId:", "", attr(out, "tags"))
CacheStoredFile(newCache, cacheId = cacheId)

# The name of the table inside the SQL database
CacheDBTableName(newCache)

CacheIsACache(newCache) # returns TRUE

# clean up
unlink(newCache, recursive = TRUE)
}
