Signal a text to the user

Signal a text to the user through an error, warning, or message.

Usage

signal_text(
  text,
  signal = c("error", "warning", "message", "quiet"),
  origin = character(0)
)

Arguments

text: character vector with text to be signalled, coerced to a character string by vect_to_char().
signal: character string indicating the type of signal to be used: "error" to throw an error, "warning" to issue a warning, "message" to show a message, or "quiet" to be quiet.
origin: Character string pasted behind text giving the origin of the message. Ignored if it is character(0).

Value

character string containing text, with a phrase indicating the origin of the signal if origin is not NULL, returned invisibly.

Details

text is coerced to a character vector using vect_to_char(), which treats zero-length input and input with length larger than one better than message() etc. that use paste0(), see the Examples. Call vect_to_char() beforehand on text for finer control of rounding and wrapping of text, see the Examples.

text is signalled through an error, warning, message, or quietly, depending on argument signal. To make text available for further queries when using signal_text() in another function, add the content of the signal as an attribute to the returned object, see the last Example.

Examples

test_text <- c("Some text", "Some other text")
try(signal_text(text = test_text, signal = "error"))
#> Error : Some text, Some other text
signal_text(text = test_text, signal = "warn")
#> Warning: Some text, Some other text
signal_text(text = test_text, signal = "message")
#> Some text, Some other text
signal_text(text = test_text, signal = "quiet")

# signal_text() handles input to 'text' with length larger than one more
# sensible than message():
test_numbers <- 11:13
signal_text(text = test_numbers, signal = "message")
#> 11, 12, 13
message(test_numbers)
#> 111213

# Newlines in 'signal' are respected:
signal_text(text = paste0(test_text, collapse = "\n"), signal = "warn")
#> Warning: Some text
#> Some other text

# 'vect_to_char()' is used to display the different NA's in the signal
# clearer than standard printing:
signal_text(text = NA_integer_, signal = "message") # prints NA_integer_
#> NA_integer_
message(NA_integer_) # prints NA
#> NA

# Call 'vect_to_char()' beforehand on 'text' for finer control of rounding
# and wrapping of text:
message(test_numbers / 7)
#> 1.571428571428571.714285714285711.85714285714286
signal_text(text = test_numbers / 7, signal = "message")
#> 1.57, 1.71, 1.86
signal_text(text = vect_to_char(x = test_numbers / 7, signif = 4, width = 15,
                                collapse = "\n"),
            signal = "message")
#> 1.571 1.714
#> 1.857

# This example shows how to make the content of the signal available for
# further queries:
signal_negative <- function(x, signal = c("error", "warning", "message", "quiet")) {
  text_signal <- "This is a negative number"
  if(x < 0) {
    progutils::signal_text(text = text_signal, signal = signal)
    attributes(x) <- list(text_signal = text_signal)
  } else {
    # Using '""' as attribute such that
    # grepl(pattern = "<text>", x = attr(x, "text_signal"), fixed = TRUE)
    # returns 'FALSE' if <text> is not found in 'text_signal' (using
    # 'character(0)' as attribute would lead to 'logical(0)' as return).
    attributes(x) <- list(text_signal = "")
  }
  x
}

res_negative <- signal_negative(x = -1, signal = "warning")
#> Warning: This is a negative number
res_positive <- signal_negative(x = 1, signal = "warning")
res_negative
#> [1] -1
#> attr(,"text_signal")
#> [1] "This is a negative number"
res_positive
#> [1] 1
#> attr(,"text_signal")
#> [1] ""
grepl(pattern = "negative", x = attr(res_negative, "text_signal"),
      ignore.case = FALSE, fixed = TRUE) # TRUE
#> [1] TRUE
grepl(pattern = "negative", x = attr(res_positive, "text_signal"),
      ignore.case = FALSE, fixed = TRUE) # FALSE
#> [1] FALSE

Usage

Arguments

Value

Details

See also

Examples