diff --git a/NAMESPACE b/NAMESPACE index e4ef366..7c6473a 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,5 +1,6 @@ # Generated by roxygen2: do not edit by hand +export(beep) export(add_logo) export(add_logo_ga) export(agresti_coull_interval) diff --git a/R/notifications.R b/R/notifications.R new file mode 100644 index 0000000..1f9c9e9 --- /dev/null +++ b/R/notifications.R @@ -0,0 +1,151 @@ +#' Send a CLI beep / desktop notification +#' +#' Plays an audible beep in the terminal and/or sends a desktop notification +#' when a long-running R script completes or reaches a milestone. +#' +#' @param msg Character. Optional message to include in the notification. +#' When `type = "notify"`, this becomes the notification body. +#' @param type Character. Notification method: +#' - `"beep"` (default): emit a terminal bell character (`\007`). +#' Works in any terminal that supports the bell. +#' - `"notify"`: send a desktop notification via `notify-send` (Linux) or +#' `osascript` (macOS). Falls back to `"beep"` if neither tool is found. +#' - `"webhook"`: POST a JSON payload to a URL. Requires `url` argument. +#' - `"all"`: play beep + send desktop notification (webhook only if `url` +#' is provided). +#' @param url Character. Webhook URL for `type = "webhook"` or `"all"`. +#' A JSON payload is POSTed with keys `message`, `status`, and `timestamp`. +#' @param status Character. Status label for the notification (default `"done"`). +#' Used in the notification title and webhook payload. +#' @param timeout Numeric. Seconds to wait for the webhook POST to complete +#' (default `5`). Ignored for non-webhook types. +#' @param quiet Logical. If `TRUE`, suppress the terminal beep even when +#' `type` includes `"beep"`. Useful for silent background runs. +#' +#' @return Invisible `NULL`. +#' +#' @section Requirements: +#' - `type = "notify"` requires `notify-send` (Linux) or `osascript` (macOS). +#' - `type = "webhook"` requires network access to the provided URL. +#' +#' @section Examples: +#' \preformatted{ +#' # Simple terminal beep +#' beep() +#' +#' # Desktop notification with message +#' beep("Analysis complete!", type = "notify") +#' +#' # Send to a webhook (e.g., Slack, Discord, custom endpoint) +#' beep("Job finished", type = "webhook", +#' url = "https://hooks.slack.com/services/...") +#' +#' # Beep + desktop notification +#' beep("Processing done", type = "all") +#' } +#' +#' @export +#' +beep <- function(msg = "done", + type = c("beep", "notify", "webhook", "all"), + url = NULL, + status = "done", + timeout = 5, + quiet = FALSE) { + type <- match.arg(type) + + # -- Terminal beep ---------------------------------------------------------- + if (!quiet && grepl("beep", type)) { + cat("\007") + flush.console() + } + + # -- Desktop notification --------------------------------------------------- + if (grepl("notify", type)) { + .send_desktop_notify(msg, status) + } + + # -- Webhook ---------------------------------------------------------------- + if (grepl("webhook", type) && !is.null(url)) { + .send_webhook(url, msg, status, timeout) + } + + invisible(NULL) +} + + +# -- Internal helpers --------------------------------------------------------- + +#' Send a desktop notification via notify-send or osascript +#' +#' @param msg Message body +#' @param status Status label for the title +#' @keywords internal +.send_desktop_notify <- function(msg, status) { + # Linux: notify-send + if (.has_command("notify-send")) { + cmd <- paste0("notify-send '", status, "' '", gsub("'", "'\\''", msg), "'") + system(cmd, ignore.stdout = TRUE, ignore.stderr = TRUE) + return(invisible(NULL)) + } + + # macOS: osascript + if (.has_command("osascript")) { + escaped_msg <- gsub('"', '\\"', msg) + escaped_status <- gsub('"', '\\"', status) + cmd <- paste0( + "osascript -e 'display notification \"", escaped_msg, + "\" with title \"", escaped_status, "\"'" + ) + system(cmd, ignore.stdout = TRUE, ignore.stderr = TRUE) + return(invisible(NULL)) + } + + # Neither tool available — silently skip + invisible(NULL) +} + + +#' POST a JSON payload to a webhook URL +#' +#' @param url Webhook URL +#' @param msg Message body +#' @param status Status label +#' @param timeout Seconds to wait for the request +#' @keywords internal +.send_webhook <- function(url, msg, status, timeout) { + payload <- jsonlite::toJSON(list( + message = msg, + status = status, + timestamp = format(Sys.time(), "%Y-%m-%dT%H:%M:%S%z") + ), auto_unbox = TRUE) + + # Use curl via system() for maximum compatibility (no extra R deps) + if (.has_command("curl")) { + cmd <- paste0( + "curl -s -X POST -H 'Content-Type: application/json' ", + "-d '", payload, "' '", url, "' ", + "--max-time ", timeout + ) + system(cmd, ignore.stdout = TRUE, ignore.stderr = TRUE) + } else if (.has_command("wget")) { + cmd <- paste0( + "wget -q -O /dev/null --post-data='", payload, + "' --header='Content-Type: application/json' ", + "--timeout=", timeout, " '", url, "'" + ) + system(cmd, ignore.stdout = TRUE, ignore.stderr = TRUE) + } + + invisible(NULL) +} + + +#' Check if a command exists on the system PATH +#' +#' @param cmd Command name +#' @return Logical +#' @keywords internal +.has_command <- function(cmd) { + Sys.which(cmd) != "" +} diff --git a/R/utils.R b/R/utils.R index 6a4fe8b..b1a0ca3 100644 --- a/R/utils.R +++ b/R/utils.R @@ -149,6 +149,9 @@ race_short_names <- function(x) { #' Sum a numeric that contains missing values and ignore missing values #' #' @param x a numeric vector +#' @param quiet Logical. If `TRUE` (default `FALSE`), suppress the warning +#' message. Useful when calling `na_sum()` inside a loop or `dplyr` pipeline +#' where the message would be emitted repeatedly. #' #' @return the sum, ignoring any missing values #' @export @@ -156,9 +159,12 @@ race_short_names <- function(x) { #' @examples #' x <- c(2, NA, 4, 9) #' na_sum(x) # 15 -na_sum <- function(x) { +#' na_sum(x, quiet = TRUE) # 15 (no message) +na_sum <- function(x, quiet = FALSE) { stopifnot(is.numeric(x)) - message("Taking a sum with missing values equal to 0, be careful!") + if (!quiet) { + message("Taking a sum with missing values equal to 0, be careful!") + } x <- na_zero(x) return(sum(x)) } diff --git a/inst/quarto/_brand.yml b/inst/quarto/_brand.yml index 73ad02a..d8c6ba3 100644 --- a/inst/quarto/_brand.yml +++ b/inst/quarto/_brand.yml @@ -2,65 +2,64 @@ # Optional but recommended — Quarto auto-applies these to HTML, PDF, and Revealjs. # https://quarto.org/docs/authoring/brand.html -brand: - meta: - name: Civilytics Consulting - description: Turning public data into clear, actionable analysis for public good. +meta: + name: Civilytics Consulting + description: Turning public data into clear, actionable analysis for public good. - logo: - small: assets/logo/civilytics-mark.svg - medium: assets/logo/civilytics-wordmark.svg - large: assets/logo/civilytics-wordmark.svg +logo: + small: assets/logo/civilytics-mark.svg + medium: assets/logo/civilytics-wordmark.svg + large: assets/logo/civilytics-wordmark.svg - color: - palette: - paper: "#FAF7F2" - paper-2: "#F2EDE4" - ink: "#0E1A2B" - ink-2: "#2B3A52" - ink-3: "#5A6A82" - navy: "#22406A" - ember: "#C25311" - ember-2: "#923D00" - teal: "#1F6F70" - plum: "#6B3A5E" - moss: "#4A6B2F" - brass: "#B8751C" - background: paper - foreground: ink - primary: navy - secondary: ember - success: moss - info: navy - warning: "#9A5F18" - danger: "#A6271D" - light: paper-2 - dark: ink - link: navy +color: + palette: + paper: "#FAF7F2" + paper-2: "#F2EDE4" + ink: "#0E1A2B" + ink-2: "#2B3A52" + ink-3: "#5A6A82" + navy: "#22406A" + ember: "#C25311" + ember-2: "#923D00" + teal: "#1F6F70" + plum: "#6B3A5E" + moss: "#4A6B2F" + brass: "#B8751C" + background: paper + foreground: ink + primary: navy + secondary: ember + success: moss + info: navy + warning: "#9A5F18" + danger: "#A6271D" + light: paper-2 + dark: ink + link: navy - typography: - fonts: - - family: "Source Serif 4" - source: google - - family: "Inter" - source: google - - family: "JetBrains Mono" - source: google - - family: "Libre Franklin" - source: google - base: - family: Inter - size: 1rem - line-height: 1.65 - headings: - family: "Libre Franklin" - weight: 800 - style: normal - line-height: 1.08 - color: ink - monospace: - family: "JetBrains Mono" - size: 0.92em - link: - color: navy - decoration: underline +typography: + fonts: + - family: "Source Serif 4" + source: google + - family: "Inter" + source: google + - family: "JetBrains Mono" + source: google + - family: "Libre Franklin" + source: google + base: + family: Inter + size: 1rem + line-height: 1.65 + headings: + family: "Libre Franklin" + weight: 800 + style: normal + line-height: 1.08 + color: ink + monospace: + family: "JetBrains Mono" + size: 0.92em + link: + color: navy + decoration: underline diff --git a/tests/testthat/test_notifications.R b/tests/testthat/test_notifications.R new file mode 100644 index 0000000..847e51f --- /dev/null +++ b/tests/testthat/test_notifications.R @@ -0,0 +1,22 @@ +# Test beep / notification function + +context("Test beep() function") + +test_that("beep() returns invisibly", { + expect_invisible(beep()) + expect_invisible(beep("test", type = "beep")) + expect_invisible(beep("test", type = "all")) +}) + +test_that("beep() with quiet=TRUE produces no output", { + expect_silent(beep("test", type = "beep", quiet = TRUE)) +}) + +test_that("beep() with type=notify is silent when no tools available", { + # When notify-send and osascript are both absent, should be silent + expect_silent(beep("test", type = "notify")) +}) + +test_that("beep() with type=webhook and no URL is silent", { + expect_silent(beep("test", type = "webhook")) +}) diff --git a/tests/testthat/test_utils.R b/tests/testthat/test_utils.R index acba675..9dd4d11 100644 --- a/tests/testthat/test_utils.R +++ b/tests/testthat/test_utils.R @@ -58,6 +58,12 @@ test_that("na_sum fails with non-numerics", { expect_error(na_sum(as.factor(1:10))) }) +test_that("na_sum quiet=TRUE suppresses the message", { + expect_message(na_sum(c(1:10, NA)), "Taking a sum") + expect_silent(na_sum(c(1:10, NA), quiet = TRUE)) + expect_equal(na_sum(c(1:10, NA), quiet = TRUE), 55) +}) + context("Test Utilities - Pretty Count")