% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cache-utils.R
\encoding{UTF-8}
\name{catr_set_cache_dir}
\alias{catr_set_cache_dir}
\alias{catr_detect_cache_dir}
\title{Set your \CRANpkg{CatastRo} cache dir}
\usage{
catr_set_cache_dir(
  cache_dir = NULL,
  overwrite = FALSE,
  install = FALSE,
  verbose = TRUE
)

catr_detect_cache_dir()
}
\arguments{
\item{cache_dir}{Path to a cache directory. On \code{NULL}, the function
stores cached files in a temporary directory (see \code{\link[base:tempdir]{base::tempdir()}}).}

\item{overwrite}{Logical. If \code{TRUE}, overwrites an existing
\code{CATASTROESP_CACHE_DIR} already present on your machine.}

\item{install}{Logical. If \code{TRUE}, installs the key on your local
machine for use in future sessions. Defaults to \code{FALSE}. If \code{cache_dir}
is \code{FALSE}, this argument is set to \code{FALSE} automatically.}

\item{verbose}{Logical. If \code{TRUE}, displays informational messages.}
}
\value{
\code{catr_set_cache_dir()} returns an (invisible) character with the path to
your \code{cache_dir}, but it is mainly called for its side effect.

\code{catr_detect_cache_dir()} returns the path to the \code{cache_dir} used in this
session.
}
\description{
Store your \code{cache_dir} path on your local machine for future sessions.
Type \code{Sys.getenv("CATASTROESP_CACHE_DIR")} to find your cached path or
use \code{\link[=catr_detect_cache_dir]{catr_detect_cache_dir()}}.
}
\details{
By default, when no \code{cache_dir} is set, the package uses a folder inside
\code{\link[base:tempdir]{base::tempdir()}} (so files are temporary and are removed when the \strong{R}
session ends). To persist a cache across \strong{R} sessions, use
\code{catr_set_cache_dir(cache_dir, install = TRUE)} which writes the chosen
path to a small configuration file under
\code{tools::R_user_dir("CatastRo", "config")}.
}
\note{
In \CRANpkg{CatastRo} >= 1.0.0 the location of the configuration file has
moved from \code{rappdirs::user_config_dir("CatastRo", "R")} to
\code{tools::R_user_dir("CatastRo", "config")}. We have implemented a
functionality that migrates previous configuration files from one
location to another with a message. This message appears only once
informing of the migration.
}
\section{Caching strategies}{


Some files can be read from their online source without caching using the
option \code{cache = FALSE}. Otherwise the source file is downloaded to
your computer. \CRANpkg{CatastRo} implements the following caching options:
\itemize{
\item For occasional use, rely on the default \code{\link[=tempdir]{tempdir()}}-based cache (no
install).
\item Modify the cache for a single session setting
\code{catr_set_cache_dir(cache_dir = "a/path/here")}.
\item For reproducible workflows, install a persistent cache with
\code{catr_set_cache_dir(cache_dir = "a/path/here", install = TRUE)}.
This cache is kept across \strong{R} sessions.
\item For caching specific files, use the \code{cache_dir} argument in the
corresponding function.
}

Sometimes cached files may be corrupt. In that case, try re-downloading
the data setting \code{update_cache = TRUE} in the corresponding function.

If you experience any problem downloading, try downloading the
corresponding file by another method and save it in your
\code{cache_dir}. Use the option \code{verbose = TRUE} for debugging the API query
and \code{\link[=catr_detect_cache_dir]{catr_detect_cache_dir()}} to identify your cached path.
}

\examples{

# Caution! It modifies your current state
\dontrun{
my_cache <- catr_detect_cache_dir()

# Set an example cache
ex <- file.path(tempdir(), "example", "cachenew")
catr_set_cache_dir(ex)

catr_detect_cache_dir()

# Restore initial cache
catr_set_cache_dir(my_cache)
identical(my_cache, catr_detect_cache_dir())
}


catr_detect_cache_dir()

}
\seealso{
\code{\link[tools:R_user_dir]{tools::R_user_dir()}}

Other cache utilities:
\code{\link[=catr_clear_cache]{catr_clear_cache()}}
}
\concept{cache utilities}
