From 7914c9fc026ef3778ae9cc7cc69f3c08ad506005 Mon Sep 17 00:00:00 2001 From: Andrew Gene Brown Date: Thu, 16 Nov 2023 20:18:07 -0800 Subject: [PATCH] Export and document `wbt_file_path()` for #119 --- DESCRIPTION | 2 +- NAMESPACE | 1 + NEWS.md | 6 ++++- R/wbt.R | 53 +++++++++++++++++++++++++++++++++++++------- man/wbt_file_path.Rd | 41 ++++++++++++++++++++++++++++++++++ 5 files changed, 93 insertions(+), 10 deletions(-) create mode 100644 man/wbt_file_path.Rd diff --git a/DESCRIPTION b/DESCRIPTION index d0be5bccd..7c531826d 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: whitebox Type: Package Title: 'WhiteboxTools' R Frontend -Version: 2.3.3 +Version: 2.3.4 Description: An R frontend for the 'WhiteboxTools' library, which is an advanced geospatial data analysis platform developed by Prof. John Lindsay at the University of Guelph's Geomorphometry and Hydrogeomatics Research Group. 'WhiteboxTools' can be used to perform common geographical information systems (GIS) analysis operations, such as cost-distance analysis, distance buffering, and raster reclassification. Remote sensing and image processing tasks include image enhancement (e.g. panchromatic sharpening, contrast adjustments), image mosaicing, numerous filtering operations, simple classification (k-means), and common image transformations. 'WhiteboxTools' also contains advanced tooling for spatial hydrological analysis (e.g. flow-accumulation, watershed delineation, stream network analysis, sink removal), terrain analysis (e.g. common terrain indices such as slope, curvatures, wetness index, hillshading; hypsometric analysis; multi-scale topographic position analysis), and LiDAR data processing. Suggested citation: Lindsay (2016) . Authors@R: c(person("Qiusheng", "Wu", email = "giswqs@gmail.com", role = c("aut")), person("Andrew", "Brown", email = "brown.andrewg@gmail.com", role = c("ctb", "cre"))) diff --git a/NAMESPACE b/NAMESPACE index 82efef9e6..0cb2aaa3c 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -158,6 +158,7 @@ export(wbt_fd8_flow_accumulation) export(wbt_fd8_pointer) export(wbt_feature_preserving_smoothing) export(wbt_fetch_analysis) +export(wbt_file_path) export(wbt_fill_burn) export(wbt_fill_depressions) export(wbt_fill_depressions_planchon_and_darboux) diff --git a/NEWS.md b/NEWS.md index ac194c5a7..555da8d4b 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,6 +1,10 @@ +# whitebox 2.3.4 + + * Exported `wbt_file_path()`, a function previously used internally for creating safe, expanded, quoted, paths for building WhiteboxTools commands. + # whitebox 2.3.3 - * The default values for `compress_rasters` and `verbose_mode` have been set to NULL to better reflect that they are derived from the WhiteboxTools settings.json file. + * The default values for `compress_rasters` and `verbose_mode` have been set to `NULL` to better reflect that they are derived from the WhiteboxTools settings.json file. * See `wbt_options()` for more details. If the user specifies these arguments in a `wbt_*()` function call then the flag will be passed in the command line call. Otherwise the default `NULL` value is ignored. Links to the corresponding option-setting functions have been added to the documentation for all `wbt_*()` tool functions. diff --git a/R/wbt.R b/R/wbt.R index 29ff98737..64bfadb51 100644 --- a/R/wbt.R +++ b/R/wbt.R @@ -1120,14 +1120,51 @@ wbt_system_call <- function(argstring, } # support for path expansion in input/output file arguments -wbt_file_path <- function(x, shell_quote = TRUE) { - stopifnot(length(x) == 1) - .shQuote <- function(x) if (shell_quote) shQuote(x) else x - sapply(x, function(y){ - if (is.character(y)) { - .shQuote(paste0(path.expand(strsplit(y, ";|,")[[1]]), collapse = ",")) - } else y - }) + +#' Prepare File Paths for WhiteboxTools Commands +#' +#' Performs path expansion with `path.expand()` and shell quotes with `shQuote()` the input paths. +#' +#' @details If an input vector contains `";"` or `","` this is considered, path expansion is performed on the substrings. If the input vector has length greater than `1`, the vector is concatenated with `","` or `";"` to create a single output string. +#' +#' @param x character. Vector of file paths or strings of file paths for passing as arguments to WhiteboxTools. +#' @param shell_quote logical. Shell quotes around result? Default: `TRUE` +#' @param delimiter character. Either `","` (default) or `";"` allowed by WhiteboxTools. +#' @param check_exists logical. Check if file(s) in x exist? Useful for input values. Default: `FALSE` +#' +#' @return character. Length 1. A safe input string for use in WhiteboxTools commands, with paths expanded and concatenated, if necessary, and optionally shell quoted. +#' @export +#' +#' @examples +#' +#' wbt_file_path("./abc.tif") +#' +#' wbt_file_path("./abc.tif;./def.tif") +#' +#' wbt_file_path("./abc.tif,./def.tif") +#' +#' wbt_file_path(c("./abc.tif", "./def.tif")) +#' +#' wbt_file_path("~/abc.tif", shell_quote = FALSE) +#' +#' wbt_file_path(c("~/abc.tif", "~/def.tif")) +#' +wbt_file_path <- function(x, shell_quote = TRUE, delimiter = ",", check_exists = FALSE) { + delimiter <- match.arg(trimws(delimiter), c(",", ";")) + x <- path.expand(strsplit( + paste0(as.character(x), collapse = ","), ";|," + )[[1]]) + if (check_exists) { + y <- !file.exists(x) + if (any(y)) { + stop(sprintf("File%s not found: %s", + ifelse(sum(y) > 1, "s",""), + paste0(x[y], collapse = ", ")), + call. = FALSE) + } + } + x <- paste0(x, collapse = delimiter) + if (shell_quote) shQuote(x) else x } #' Convenience method for path to sample DEM diff --git a/man/wbt_file_path.Rd b/man/wbt_file_path.Rd new file mode 100644 index 000000000..42dbba784 --- /dev/null +++ b/man/wbt_file_path.Rd @@ -0,0 +1,41 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/wbt.R +\name{wbt_file_path} +\alias{wbt_file_path} +\title{Prepare File Paths for WhiteboxTools Commands} +\usage{ +wbt_file_path(x, shell_quote = TRUE, delimiter = ",", check_exists = FALSE) +} +\arguments{ +\item{x}{character. Vector of file paths or strings of file paths for passing as arguments to WhiteboxTools.} + +\item{shell_quote}{logical. Shell quotes around result? Default: \code{TRUE}} + +\item{delimiter}{character. Either \code{","} (default) or \code{";"} allowed by WhiteboxTools.} + +\item{check_exists}{logical. Check if file(s) in x exist? Useful for input values. Default: \code{FALSE}} +} +\value{ +character. Length 1. A safe input string for use in WhiteboxTools commands, with paths expanded and concatenated, if necessary, and optionally shell quoted. +} +\description{ +Performs path expansion with \code{path.expand()} and shell quotes with \code{shQuote()} the input paths. +} +\details{ +If an input vector contains \code{";"} or \code{","} this is considered, path expansion is performed on the substrings. If the input vector has length greater than \code{1}, the vector is concatenated with \code{","} or \code{";"} to create a single output string. +} +\examples{ + +wbt_file_path("./abc.tif") + +wbt_file_path("./abc.tif;./def.tif") + +wbt_file_path("./abc.tif,./def.tif") + +wbt_file_path(c("./abc.tif", "./def.tif")) + +wbt_file_path("~/abc.tif", shell_quote = FALSE) + +wbt_file_path(c("~/abc.tif", "~/def.tif")) + +}