R/path.R

In jeanmathieupotvin/dfp: Directories, Files and Paths

#' @title Construct generic paths
#'
#' @description Construct generic paths pointing to resources, typically unique
#' locations in the OS file system.
#'
#' @param ... arbitrary character vectors of same length (**atoms**).
#'
#' @param sep a character. The seperator to use when constructing paths.
#'
#' @return a character encoded in "UTF-8".
#'
#' @details Vector recycling is disabled by default. Passing vectors of
#' different lengths to `...` will result in an error. Since the underlying
#' implementation is based on [base::file.path()], it should be fast and
#' efficient.
#'
#' @section Paths:
#' A path specifies a unique location in a file system and acts as a
#' Uniform Resource Locator (URL) of a file or a directory. It is the general
#' form of the name of that resource.
#'
#' @section Atoms:
#' A path is constructed by using an arbitrary number of **atoms**: individual
#' components of a path. In \pkg{dfp}, atoms are considered to be the building
#' blocks of a path. They are usually taken from a directory tree hierarchy.
#' Atoms are glued together by using a common seperator.
#'
#' As an example, consider the following path (with a slash as the separator).
#'
#' ```
#' C:/home/user/docs/letters/letter.txt
#' ```
#' In that path, the atoms are `C:`, `home`, `user`, `docs`, `letters` and
#' `letter.txt`. Together, they define the unique location of the `letter.txt`
#' file in the file system.
#'
#' @examples
#' path(c("C:", "D:"), c("home", "apps"), c("user", "bin"), c("docs", "abc.txt"))
#' path(list("C:", "D:"), list("user", "bin"), list("docs", "letter.txt"))
#'
#' ## Encoding of output should be "UTF-8" (if it contain "UTF-8" characters).
#' path_example1 <- path("this", "is", "a", "test.r")
#' Encoding(path_example1)
#'
#' path_example2 <- path("àé", "is", "a", "test.r")
#' Encoding(path_example2)
#'
#' @export
path <- function(..., sep = .Platform$file.sep)
{
    atoms <- list(...)
    atoms_lens <- lengths(atoms)

    if (any(atoms_lens != atoms_lens[[1L]])) {
        stop("atoms passed to ... must have equal lengths.",
             call. = FALSE)
    }

    structure(dontCheck(enc2utf8(.Internal(file.path(atoms, fsep = sep)))),
              sep   = sep,
              class = c("path", "character"))
}

is_path <- function(x)
{
    inherits(x, "path")
}

sep <- function(path)
{
    if (!is_path(path)) {
        stop("input is not of class 'path'.", call. = FALSE)
    }

    attr(path, "sep", TRUE)
}

atoms <- function(path)
{
    if (!is_path(path)) {
        stop("input is not of class 'path'.", call. = FALSE)
    }

    strsplit(path, sep(path))
}