Export and document wbt_file_path() for #119

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) <doi:10.1016/j.cageo.2016.07.003>.
 Authors@R: c(person("Qiusheng", "Wu", email = "[email protected]", role = c("aut")),
              person("Andrew", "Brown", email = "[email protected]", role = c("ctb", "cre")))

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)

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.
 

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