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())

Arguments

...

One or more character strings. For most of these functions, if multiple strings are passed these will be pasted together.

.envir

This argument is just to inherit the parent frame in the (likely) event that the function is used within another function.

old, new

The old name of a function, argument, or value, and the name that replaces it.

stage

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.

type

What the old name names: a "function", an "argument", or a "value" of an argument.

why

An optional sentence saying why the name changed, or how to get the same result with the new one.

msg

A message to give instead of the one built from old and new.

new_pkg, old_pkg

The package that a function moved to, and the package it moved from.

version

The version of old_pkg in which the function moved.

pkg

The name of a package that a function needs, usually one the package only suggests.

ask

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.

Details

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.

Verbosity

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').