Perform a task once in an R session

Perform a task once in an R session, e.g., emit a message or warning. Then give users an optional hint on how not to perform this task at all.

Usage

do_once(
  task,
  option,
  hint = c("You will not see this message again in this R session.",
    "If you never want to see this message,",
    sprintf("you may set options(%s = FALSE) in your .Rprofile.", option))
)

Arguments

task

Any R code expression to be evaluated once to perform a task, e.g., warning('Danger!') or message('Today is ', Sys.Date()).

option

An R option name. This name should be as unique as possible in options(). After the task has been successfully performed, this option will be set to FALSE in the current R session, to prevent the task from being performed again the next time when do_once() is called.

hint

A character vector to provide a hint to users on how not to perform the task or see the message again in the current R session. Set hint = "" if you do not want to provide the hint.

Value

The value returned by the task, invisibly.

Examples

do_once(message("Today's date is ", Sys.Date()), "xfun.date.reminder")
#> Today's date is 2026-07-02
#> You will not see this message again in this R session. If you never want to see this message, you may set options(xfun.date.reminder = FALSE) in your .Rprofile.
# if you run it again, it will not emit the message again
do_once(message("Today's date is ", Sys.Date()), "xfun.date.reminder")

do_once({
    Sys.sleep(2)
    1 + 1
}, "xfun.task.1plus1")
#> You will not see this message again in this R session. If you never want to see this message, you may set options(xfun.task.1plus1 = FALSE) in your .Rprofile.
do_once({
    Sys.sleep(2)
    1 + 1
}, "xfun.task.1plus1")