More path functionality

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: qgisprocess
 Title: Use 'QGIS' Processing Algorithms
-Version: 0.1.0.9181
+Version: 0.1.0.91812
 Authors@R: c(
     person("Dewey", "Dunnington", , "dewey@fishandwhistle.net", role = "aut",
            comment = c(ORCID = "0000-0002-9415-4582", affiliation = "Voltron Data")),

NAMESPACE

@@ -71,6 +71,7 @@ export(qgis_configure)
 export(qgis_description)
 export(qgis_detect_macos)
 export(qgis_detect_macos_paths)
+export(qgis_detect_paths)
 export(qgis_detect_windows)
 export(qgis_detect_windows_paths)
 export(qgis_dict_input)

NEWS.md

@@ -2,16 +2,21 @@
 
 ## New features
 
-- Add vector support for {terra} (#184).
+- Add vector support for `{terra}` (#184).
 This makes it possible to use `SpatVector` or `SpatVectorProxy` objects as input arguments, and to coerce processing results to `SpatVector` or `SpatVectorProxy`.
 - `qgis_detect_windows_paths()` and `qgis_detect_macos_paths()` put paths at the top that contain a QGIS version string and these paths are sorted according to decreasing QGIS version (#189).
-This lets `qgis_configure()` prefer the newest QGIS version from `qgis_process` file paths that have a version string.
+This lets `qgis_configure()` select the newest QGIS version among `qgis_process` file paths that have a version string.
+Furthermore, a wrapper `qgis_detect_paths()` has been added that works on both Windows and macOS (#192).
 
-## Other changes
+## Minor changes
 
 - Allow half-configured states with abundant messages, so that remaining functionality can be used in debugging or even for some real stuff (#177).
-- `qgis_run_algorithm()` documentation gains a section on QGIS models and scripts (8a20669).
-- Solve a CRAN check error on `r-oldrel-macos-x86_64`, by adding support for {stars} 0.5-5 (#175).
+- `qgis_run_algorithm()` documentation gains a section on QGIS models and scripts ([8a20669](https://github.com/r-spatial/qgisprocess/commit/8a20669ea50b4b9c14194dd864ed119e137732a9)).
+- An option `qgisprocess.detect_newer_qgis` is available (mirrored by environment variable `R_QGISPROCESS_DETECT_NEWER_QGIS`) for Windows and macOS (#192).
+If set as `TRUE`, during package loading `{qgisprocess}` will check whether a more recent (standalone) QGIS version is also installed while the package cache still dictates to use an older version.
+In this specific scenario a question will be asked to switch to the newer version.
+Without setting this option default behaviour remains in place, i.e. the user must manually intervene by setting the `qgisprocess.path` option, or by uninstalling the older QGIS version.
+- Solve a CRAN check error on `r-oldrel-macos-x86_64`, by adding support for `{stars}` 0.5-5 (#175).
 
 # qgisprocess 0.1.0
 

R/qgis-configure.R

@@ -158,6 +158,70 @@ qgis_configure <- function(quiet = FALSE, use_cached_data = FALSE) {
             return(invisible(has_qgis()))
           }
 
+          # CACHE CONDITION: the path element does not contradict the
+          # environment variable/option to automatically switch to a newer
+          # available QGIS version
+          if (is_windows() || is_macos()) {
+            opt <- getOption(
+              "qgisprocess.detect_newer_qgis",
+              Sys.getenv("R_QGISPROCESS_DETECT_NEWER_QGIS")
+            )
+            assert_that(
+              assertthat::is.flag(opt) ||
+                (assertthat::is.string(opt) && opt %in% c("", "TRUE", "FALSE", "true", "false")),
+              msg = "Option 'qgisprocess.detect_newer_qgis' must be 'TRUE' or 'FALSE'."
+            )
+            if (identical(opt, "")) opt <- NA
+            opt || grepl("TRUE|true", opt)
+
+            first_qgis <- qgis_detect_paths()[1]
+            newer_available <- !is.na(extract_version_from_paths(first_qgis)) &&
+              !identical(cached_data$path, first_qgis)
+
+            if (isTRUE(opt) && isTRUE(newer_available) && interactive()) {
+              packageStartupMessage()
+              packageStartupMessage(glue(
+                "A newer QGIS installation seems to be available: ",
+                "{extract_version_from_paths(first_qgis)}."
+              ))
+              answer <- ""
+              while (!grepl("^[Yy](?:[Ee][Ss])?$|^[Nn](?:[Oo])?$", answer)) {
+                answer <- readline("Do you want to try it and rebuild the cache? (y/n) ")
+              }
+              if (grepl("^[Yy]", answer)) {
+                newer_ok <- FALSE
+                tryCatch(
+                  {
+                    qgis_run(path = first_qgis)
+                    newer_ok <- TRUE
+                  },
+                  error = function(e) {
+                    packageStartupMessage(
+                      glue(
+                        "'{first_qgis}' does not work as expected.\n",
+                        "So will not try it further."
+                      )
+                    )
+                  }
+                )
+                if (newer_ok) {
+                  packageStartupMessage(
+                    "Will try to reconfigure qgisprocess and build new cache ..."
+                  )
+                  qgis_reconfigure(cache_data_file = cache_data_file, quiet = quiet)
+                  return(invisible(has_qgis()))
+                }
+              } else if (!quiet) {
+                packageStartupMessage(
+                  "\nNOTE: if you don't want to autodetect QGIS version updates ",
+                  "in the future, unset the qgisprocess.detect_newer_qgis ",
+                  "option or the R_QGISPROCESS_DETECT_NEWER_QGIS environment ",
+                  "variable."
+                )
+              }
+            }
+          }
+
           # CACHE CONDITION: the cached QGIS version equals the one reported by
           # qgis_process
 

R/qgis-detect.R

@@ -1,8 +1,10 @@
-#' Detect QGIS installations that provide the 'qgis_process' command
+#' Detect QGIS installations with 'qgis_process' on Windows and macOS
 #'
 #' Discovers existing 'qgis_process' executables on the system and returns their
 #' filepath.
 #' Only available for Windows and macOS systems.
+#' `qgis_detect_paths()` is a shortcut to `qgis_detect_windows_paths()` on
+#' Windows and `qgis_detect_macos_paths()` on macOS.
 #'
 #' @concept functions to manage and explore QGIS and qgisprocess
 #'
@@ -16,15 +18,33 @@
 #'
 #' @param drive_letter The drive letter on which to search. By default,
 #'   this is the same drive letter as the R executable.
+#'   Only applicable to Windows.
 #'
 #' @returns A character vector of possible paths to the 'qgis_process'
 #' executable.
 #' @export
 #'
 #' @examples
-#' if (.Platform$OS.type == "windows") qgis_detect_windows_paths()
-#' if (Sys.info()["sysname"] == "Darwin") qgis_detect_macos_paths()
-#'
+#' if (.Platform$OS.type == "windows") {
+#'   qgis_detect_paths()
+#'   identical(qgis_detect_windows_paths(), qgis_detect_paths())
+#' }
+#' if (Sys.info()["sysname"] == "Darwin") {
+#'   qgis_detect_paths()
+#'   identical(qgis_detect_macos_paths(), qgis_detect_paths())
+#' }
+qgis_detect_paths <- function(drive_letter = strsplit(R.home(), ":")[[1]][1]) {
+  if (is_windows()) {
+    qgis_detect_windows_paths(drive_letter = drive_letter)
+  } else if (is_macos()) {
+    qgis_detect_macos_paths()
+  } else {
+    abort("Can use `qgis_detect_paths()` on Windows and macOS only.")
+  }
+}
+
+#' @rdname qgis_detect_paths
+#' @export
 qgis_detect_windows_paths <- function(drive_letter = strsplit(R.home(), ":")[[1]][1]) {
   if (!is_windows()) {
     abort("Can't use `qgis_detect_windows_paths()` on a non-windows platform.")
@@ -50,7 +70,7 @@ qgis_detect_windows_paths <- function(drive_letter = strsplit(R.home(), ":")[[1]
   sort_paths(possible_locs_win)
 }
 
-#' @rdname qgis_detect_windows_paths
+#' @rdname qgis_detect_paths
 #' @export
 qgis_detect_macos_paths <- function() {
   if (!is_macos()) {

tests/testthat/test-qgis-detect.R

@@ -14,6 +14,16 @@ test_that("qgis_detect_windows_paths() works", {
   }
 })
 
+test_that("qgis_detect_paths() works", {
+  if (is_windows()) {
+    expect_identical(qgis_detect_paths(), qgis_detect_windows_paths())
+  } else if (is_macos()) {
+    expect_identical(qgis_detect_paths(), qgis_detect_macos_paths())
+  } else {
+    expect_error(qgis_detect_paths(), "only")
+  }
+})
+
 test_that("extract_version_from_paths() works", {
   expect_identical(extract_version_from_paths(character()), character())
   path <- "/QGIS 3.28.6/bin/qgis_process-qgis-ltr.bat"