From 40056926baa080b6214426ace6f6016b7720a267 Mon Sep 17 00:00:00 2001
From: LTLA <infinite.monkeys.with.keyboards@gmail.com>
Date: Mon, 25 Nov 2024 12:19:43 -0800
Subject: [PATCH] Emit a message/warning when the search results are truncated.

---
 DESCRIPTION                 |  4 ++--
 R/query.R                   | 25 +++++++++++++++++++++++--
 man/query.Rd                | 14 +++++++++++++-
 tests/testthat/test-query.R | 16 ++++++++++++++++
 4 files changed, 54 insertions(+), 5 deletions(-)

diff --git a/DESCRIPTION b/DESCRIPTION
index 932f177..d57b4e5 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: SewerRat
-Version: 0.3.1
-Date: 2024-11-06
+Version: 0.3.2
+Date: 2024-11-25
 Title: Client for the SewerRat API
 Description: 
     Search metadata files across a shared filesystem via the SewerRat API.
diff --git a/R/query.R b/R/query.R
index 7805f08..d021239 100644
--- a/R/query.R
+++ b/R/query.R
@@ -14,6 +14,8 @@
 #' @param until A \link{POSIXt} object to filter out newer files, i.e., only files older than \code{until} will be retained.
 #' If missing, no filtering is applied to remove new files.
 #' @param number Integer specifying the maximum number of results to return.
+#' @param on.truncation String specifying what to do when the number of results exceeds \code{number}.
+#' Either \code{"warning"}, \code{"message"}, or \code{"none"}.
 #' @param url String containing the URL to the SewerRat REST API.
 #' @param results List containing the output of \code{query}.
 #'
@@ -83,7 +85,8 @@
 #' formatQueryResults(q)
 #' @export
 #' @import httr2
-query <- function(text, user, path, from, until, url, number=100) {
+#' @importFrom utils head
+query <- function(text, user, path, from, until, url, number=100, on.truncation=c("message", "warning", "none")) {
     conditions <- list()
 
     if (!missing(text)) {
@@ -114,7 +117,13 @@ query <- function(text, user, path, from, until, url, number=100) {
         stop("at least one search filter must be present")
     }
 
-    stub <- paste0("/query?translate=true&limit=", number)
+    on.truncation <- match.arg(on.truncation)
+    if (on.truncation != "none") {
+        original.number <- number
+        number <- number + 1L
+    }
+
+    stub <- paste0("/query?translate=true")
     collected <- list()
 
     while (length(collected) < number) {
@@ -133,6 +142,18 @@ query <- function(text, user, path, from, until, url, number=100) {
         }
     }
 
+    if (on.truncation != "none") {
+        if (original.number < length(collected)) {
+            msg <- sprintf("truncated query results to the first %i matches", original.number)
+            if (on.truncation == "warning") {
+                warning(msg)
+            } else {
+                message(msg)
+            }
+        }
+        collected <- head(collected, original.number)
+    }
+
     collected
 }
 
diff --git a/man/query.Rd b/man/query.Rd
index 3ed19ec..c02a847 100644
--- a/man/query.Rd
+++ b/man/query.Rd
@@ -5,7 +5,16 @@
 \alias{formatQueryResults}
 \title{Query metadata}
 \usage{
-query(text, user, path, from, until, url, number = 100)
+query(
+  text,
+  user,
+  path,
+  from,
+  until,
+  url,
+  number = 100,
+  on.truncation = c("message", "warning", "none")
+)
 
 formatQueryResults(results)
 }
@@ -29,6 +38,9 @@ If missing, no filtering is applied to remove new files.}
 
 \item{number}{Integer specifying the maximum number of results to return.}
 
+\item{on.truncation}{String specifying what to do when the number of results exceeds \code{number}.
+Either \code{"warning"}, \code{"message"}, or \code{"none"}.}
+
 \item{results}{List containing the output of \code{query}.}
 }
 \value{
diff --git a/tests/testthat/test-query.R b/tests/testthat/test-query.R
index ac1033c..ee9d92f 100644
--- a/tests/testthat/test-query.R
+++ b/tests/testthat/test-query.R
@@ -14,6 +14,22 @@ write(file=file.path(mydir, "diet", "metadata.json"),
 # Registering it:
 register(mydir, "metadata.json", url=info$url)
 
+test_that("query works as expected", {
+    q <- query("lun*", url=info$url)
+    expect_gte(length(q), 2L)
+})
+
+test_that("query works with truncation", {
+    expect_message(q <- query("lun*", url=info$url, number=0), "truncated")
+    expect_identical(length(q), 0L)
+
+    expect_warning(q <- query("lun*", url=info$url, number=0, on.truncation="warning"), "truncated")
+    expect_identical(length(q), 0L)
+
+    expect_warning(q <- query("lun*", url=info$url, number=0, on.truncation="none"), NA)
+    expect_identical(length(q), 0L)
+})
+
 test_that("formatQueryResults works properly", {
     q <- query("lun*", url=info$url)
     res <- formatQueryResults(q)