R/read_access.R

In fileaccess: File and Directory Access Validation

#' Check Whether File or Directory is Readable
#'
#' Validates whether a file or directory exists and can be accessed
#' for reading. Supports both local and UNC network paths.
#'
#' @param path Character string. Full path to file or directory.
#'
#' @return A list of class \code{read_access_result} containing:
#' \itemize{
#'   \item path - Normalized input path
#'   \item exists - TRUE/FALSE
#'   \item type - "File" or "Directory"
#'   \item readable - TRUE/FALSE
#'   \item status - Overall status message
#' }
#'
#' @examples
#' # Check a temporary directory
#' result <- read.access(tempdir())
#' print(result)
#'
#' # Check an existing temporary file
#' tmp <- tempfile()
#' writeLines("hello", tmp)
#' result <- read.access(tmp)
#' print(result)
#' unlink(tmp)
#'
#' # Check a path that does not exist
#' result <- read.access(file.path(tempdir(), "no_such_file.csv"))
#' print(result)
#'
#' \donttest{
#' # UNC network path (requires network access)
#' read.access("//server/share/data/file.csv")
#' }
#'
#' @export
read.access <- function(path) {
  if (!is.character(path) || length(path) != 1 || is.na(path)) {
    stop("path must be a non-empty character string")
  }

  is_unc <- grepl("^[/\\\\]{2}", path)
  path_norm <- if (is_unc) {
    path
  } else {
    tryCatch(
      normalizePath(path, winslash = "/", mustWork = FALSE),
      error = function(e) path
    )
  }

  exists <- file.exists(path_norm)

  if (!exists) {
    result <- list(
      path     = path_norm,
      exists   = FALSE,
      type     = NA_character_,
      readable = FALSE,
      status   = "Path does not exist"
    )
    class(result) <- "read_access_result"
    return(result)
  }

  info <- file.info(path_norm)
  type <- ifelse(info$isdir, "Directory", "File")

  readable <- tryCatch({
    if (info$isdir) {
      list.files(path_norm)
    } else {
      con <- file(path_norm, open = "r")
      close(con)
    }
    TRUE
  }, error = function(e) FALSE)

  result <- list(
    path     = path_norm,
    exists   = TRUE,
    type     = type,
    readable = readable,
    status   = ifelse(readable, "Readable", "Not readable")
  )
  class(result) <- "read_access_result"
  return(result)
}

#' @export
print.read_access_result <- function(x, ...) {
  cat("\n")
  cat("========================================\n")
  cat("READ ACCESS REPORT\n")
  cat("========================================\n\n")
  cat("Path     :", x$path,     "\n")
  cat("Exists   :", x$exists,   "\n")
  cat("Type     :", x$type,     "\n")
  cat("Readable :", x$readable, "\n")
  cat("Status   :", x$status,   "\n")
  cat("\n========================================\n")
  invisible(x)
}