onetime_message_confirm {onetime}

Print a message, and ask for confirmation to hide it in future

Description

This uses readline() to ask the user if the message should be shown again in future.

Usage

onetime_message_confirm(
  ...,
  id = deprecate_calling_package(),
  path = default_lockfile_dir(),
  expiry = NULL,
  confirm_prompt = "Show this message again? [yN] ",
  confirm_answers = c("N", "n", "No", "no"),
  default_answer = "N",
  require_permission = FALSE,
  without_permission = "warn",
  noninteractive = paste0("To hide this message in future, run:\n",
    "  onetime::onetime_mark_as_done(id = \"", id, "\")"),
  message = .Deprecated()
)

Arguments

...

Passed to message().

id

Unique ID string. If this is unset, the name of the calling package will be used. Since onetime 0.2.0, not setting id is deprecated.

path

Directory to store lockfiles. The default uses a unique directory corresponding to the calling package, beneath rappdirs::user_config_dir(). Normally you should leave this as the default.

expiry

difftime() or e.g. lubridate::duration() object. After this length of time, code will be run again.

confirm_prompt

Character string. Question to prompt the user to hide the message in future.

confirm_answers

Character vector. Answers which will cause the message to be hidden in future.

default_answer

Character string. Default answer if user simply presses return.

require_permission

Logical. Ask permission to store files on the user's computer, if this hasn't been granted? Setting this to FALSE overrides without_permission.

without_permission

Character string. What to do if the user hasn't given permission to store files? "warn" runs the action with an extra warning; "run" runs the action with no warning; "pass" does nothing and returns the default; "stop" throws an error; "ask" asks for permission using check_ok_to_store(), and returns the default if it is not granted.

noninteractive

String. Additional message to send in non-interactive sessions. Set to NULL to do nothing in non-interactive sessions. The default tells the user how to manually mark the message as done.

message

Deprecated. Use unnamed arguments ... instead.

Details

By default, the message will be hidden if the user answers "n", "No", or "N", or just presses return to the prompt question.

Unlike other onetime functions, onetime_message_confirm() doesn't by default require permission to store files on the user's computer. The assumption is that saying "Don't show this message again" counts as granting permission (just for this one message). You can ask for broader permission by setting require_permission = TRUE and without_permission = "ask".

Value

• NULL if the message was not shown (shown already or non-interactive session and noninteractive was NULL).

• TRUE if the user confirmed, i.e. chose to hide the message.

• FALSE if the message was shown but the user did not confirm (did not choose to hide the message, or non-interactive session and noninteractive was not NULL).

Results are returned invisibly.

Note that by default, TRUE is returned when the user answers "no" to "Show this message again?" and FALSE is returned when the user answers "yes".

Examples

oo <- options(onetime.dir = tempdir(check = TRUE))
id <- sample(10000L, 1L)
onetime_message_confirm("A message to show one or more times", id = id)

onetime_reset(id = id)
options(oo)