These functions wrap {cli} functions and elements
to build an attractive command line interface (CLI).
They divide into those that change what a function does
and those that only report what it did.
A call that changes control flow always fires, whatever the verbosity, because silencing it would let the code it guards run on and return a wrong answer instead of an explanation:
snet_abort() for an error the user has to fix.
snet_unavailable() for a feature that is not yet available.
snet_warn() for a result the user should not trust without reading,
such as a value that is dropped or a name that does not match.
snet_deprecated() for an old name of a function, argument, or value.
An old name that is only superseded is reported as snet_minor_info().
snet_moved() for a function that moved to another package.
snet_requires() for a package that a function needs and that is not
installed.
A call that only reports is silenced under the default verbosity:
snet_info() for what a function chose on the user's behalf.
snet_success() for the completion of a long task.
snet_progress_step() and the other snet_progress_*() functions
for a progress bar.
snet_minor_info() for the bookkeeping a function did on the way,
such as which column it renamed.
snet_prompt() asks the user something, so it always shows.
snet_info(..., .envir = parent.frame())
snet_minor_info(..., .envir = parent.frame())
snet_warn(..., .envir = parent.frame())
snet_abort(..., .envir = parent.frame())
snet_success(..., .envir = parent.frame())
snet_prompt(..., .envir = parent.frame())
snet_deprecated(
old,
new,
stage = c("deprecated", "superseded", "defunct"),
type = c("function", "argument", "value"),
why = NULL,
msg = NULL,
.envir = parent.frame()
)
snet_moved(
old,
new,
new_pkg = "netrics",
version = NULL,
old_pkg = "manynet",
stage = c("defunct", "deprecated"),
.envir = parent.frame()
)
snet_requires(
pkg,
why = "to run this function",
ask = interactive(),
.envir = parent.frame()
)
snet_unavailable(..., .envir = parent.frame())One or more character strings. For most of these functions, if multiple strings are passed these will be pasted together.
This argument is just to inherit the parent frame in the (likely) event that the function is used within another function.
The old name of a function, argument, or value, and the name that replaces it.
How far the old name is on its way out:
"superseded" still works without a word, since a released package
that cannot yet be released again may use it.
It is reported only under the 'debug' verbosity.
"deprecated" still works, but warns whatever the verbosity, with the
class "deprecatedWarning" that base::.Deprecated() gives,
so that the warning can be caught or silenced as that one can.
"defunct" no longer works, and aborts with the class
"defunctError" that base::.Defunct() gives.
What the old name names: a "function", an "argument",
or a "value" of an argument.
An optional sentence saying why the name changed, or how to get the same result with the new one.
A message to give instead of the one built from old and new.
The package that a function moved to, and the package it moved from.
The version of old_pkg in which the function moved.
The name of a package that a function needs, usually one the package only suggests.
Whether to offer to install the package where it is missing. By default this is offered only in an interactive session, since a script would stall on the question.
snet_moved() tells the user that a function moved to another package,
and how to install that package where it is missing.
By default it then aborts, since the old name is defunct.
With stage = "deprecated" it warns instead, so that a shim can go on to
call the function in its new package.
snet_requires() checks that a package is installed before a function
uses it, and aborts with the command to install it where it is not.
The snet_verbosity option takes four levels, each adding one thing to
the one before it:
'quiet', the default, reports nothing that is not an error,
a warning, or a prompt.
'normal' adds snet_info() and snet_success(),
so that a user learns what a function chose on their behalf.
'verbose' adds the progress bars,
which reassure a user that a long task is running.
'debug' adds snet_minor_info(),
which reports exhaustively what a function did on the way.
Set one with, for example, options(snet_verbosity = 'verbose').