Package 'rmorielite'

Resolve the package cache directory

Description

Returns the directory rmorielite uses for cached resources. By default this is a sub-tree of the R session temporary directory (tempdir()) — files are cleaned up automatically when R exits, in line with the CRAN policy that packages must not write outside the session temp area without explicit user consent.

Usage

rmorielite_cache_dir(
  which = c("cache", "data", "config"),
  create = TRUE,
  persistent = NULL
)

Arguments

which	One of "data", "cache", "config"; matches the which argument of tools::R_user_dir(). Defaults to "cache".
create	Logical. If TRUE (the default), create the directory recursively if it does not yet exist.
persistent	Logical or NULL. If NULL (the default), reads the environment variable RMORIELITE_PERSISTENT_CACHE. If TRUE, uses tools::R_user_dir(); if FALSE, uses tempdir().

Details

To opt in to a persistent cache that survives R sessions, set the environment variable RMORIELITE_PERSISTENT_CACHE=1 or pass persistent = TRUE. The persistent location follows R's official convention via tools::R_user_dir() — on macOS that is ⁠~/Library/Application Support/.../rmorielite⁠, on Windows ⁠%LOCALAPPDATA%\R\.../rmorielite⁠, and on Linux ⁠$XDG_DATA_HOME/R/rmorielite⁠ (or ⁠~/.local/share/R/rmorielite⁠ if XDG_DATA_HOME is unset).

Value

A character scalar: the absolute path of the directory.

Examples

rmorielite_cache_dir()                  # default: session tempdir
rmorielite_cache_dir(persistent = TRUE) # opt in to R_user_dir

---

Resolve a CKAN resource by name pattern

Description

Queries a CKAN open-data portal's package_show endpoint and returns metadata for the first resource whose name field matches a supplied regular expression. CKAN powers many government open-data portals (Ontario, UK, Canada, US federal); resource UUIDs occasionally change between portal updates but resource names are usually stable, so name-pattern matching survives portal reslugs.

Usage

rmorielite_ckan_resolve(portal, package_slug, name_pattern, timeout = 30)

Arguments

portal	Base URL of the CKAN portal, without trailing slash. Example: "https://data.ontario.ca".
package_slug	CKAN package slug. Example: "data-on-inmates-in-ontario".
name_pattern	PCRE-compatible regex applied case-insensitively to each resource's name field. The first match wins.
timeout	Request timeout in seconds. Default 30.

Value

A list with elements name, url, format, resource_id, and package_slug, or NULL if the package is not found, the API call fails, or no resource matches.

Examples

res <- rmorielite_ckan_resolve(
  portal        = "https://data.ontario.ca",
  package_slug  = "data-on-inmates-in-ontario",
  name_pattern  = "Restrictive.?Confinement.*Detailed.?Dataset"
)
if (!is.null(res)) res$url

---

Polite, cache-aware HTTPS fetch

Description

Downloads a single URL to the per-user cache directory (see rmorielite_cache_dir()) using httr2 with built-in throttling and exponential-backoff retry on 429/5xx. If a non-empty cached copy at the same target path already exists, the download is skipped and the cached path is returned.

Usage

rmorielite_fetch(
  url,
  dest_basename = NULL,
  rate = 4,
  force = FALSE,
  max_tries = 3L
)

Arguments

url	The URL to fetch.
dest_basename	Filename (no path) under which to cache the result. Defaults to the URL's basename.
rate	Requests per second. Default 4.
force	If TRUE, re-download even if a cached copy exists. Default FALSE.
max_tries	Maximum retry attempts on transient errors (429, 5xx). Default 3.

Details

Throttling and retry are delegated to httr2::req_throttle() and httr2::req_retry(). The default rate cap of 4 requests per second matches the polite-by-default conventions used by major public-data CKAN portals.

Value

A character scalar: the absolute path of the cached file.

Examples

path <- rmorielite_fetch(
  "https://data.ontario.ca/api/3/action/package_list"
)
file.exists(path)

---