Write messages based on verbosity level

The msg function is a general function for writing messages to the console based on options set using the options package. As a default, an option called verbosity_level set in the package defining a function calling msg is used. If a global option with prefix zephyr. is set, it will overwrite the package level option.

Valid values are quiet, verbose and debug. verbose is used in levels_to_write vector argument when the developer wants to inform the user about something. debug is ised when the developer wants to give the user extra information that can help with debugging. See example for possible use case.

Usage

msg(
  message,
  levels_to_write = c("verbose", "debug"),
  msg_fun = cli::cli_alert_info,
  ...,
  verbosity_level = NULL,
  which = -1,
  .envir = parent.frame()
)

msg_debug(
  message,
  ...,
  verbosity_level = NULL,
  which = -1,
  .envir = parent.frame()
)

msg_success(
  message,
  ...,
  verbosity_level = NULL,
  which = -1,
  .envir = parent.frame()
)

Arguments

message: character of message to write
levels_to_write: character vector of levels of verbosity for which to display the message. Valid values are quiet, verbose and debug
msg_fun: function taking message as first argument. Usually a cli_... function
...: Additional arguments passed to msg_fun
verbosity_level: The verbosity level to use. If NULL, the function will use the which argument to determine the environment in which to find and option called verbosity_level. By default, it will look in the environment of the function calling msg(_...). If no option is set in this calling environment, it will look in the zephyr namespace.
which: integer passed to sys.function() in case verbosity_level = NULL. Default is -1, meaning it will look in the environment of the function calling msg(_...).
.envir: environment passed to msg_fun

Value

None

Details

The msg function is a general function, which can be used to write messages based on options.

The msg_debug function is a wrapper around msg with levels_to_write = "debug" and msg_fun = cli::cli_inform, while the msg_success function is a wrapper around msg with levels_to_write = c("verbose", "debug") and msg_fun = cli::cli_alert_success.

Examples

filter_data <- function(data, infilter, ...) {

  #Defusing the filter arguments
  infilter_e <- rlang::enquo(infilter)
  infilter_lb <- rlang::as_label(infilter_e)

  msg("Attempting to filter {.field data} by {.field {infilter_lb}}",
    levels_to_write = c("verbose", "debug"),
    msg_fun = cli::cli_h2)

  #Adding a debug message that only will appear if verbosity level is set to
  "debug"
  msg_debug("Trying to filter data")

  data |>
    dplyr::filter({{infilter}})

  msg_success("Data filtered by {.field {infilter_lb}}")
 }

withr::with_options(
list(zephyr.verbosity_level = "verbose"),
     filter_data(data = cars, infilter = speed > 12)
)
#> 
#> ── Attempting to filter data by speed > 12 ──
#> 
#> ✔ Data filtered by speed > 12

withr::with_options(
  list(zephyr.verbosity_level = "debug"),
       filter_data(data = cars, infilter = speed > 12)
)
#> 
#> ── Attempting to filter data by speed > 12 ──
#> 
#> Trying to filter data
#> ✔ Data filtered by speed > 12