local_use_cli: Use cli to format error messages

In rlang: Functions for Base Types and Core R and 'Tidyverse' Features

Use cli to format error messages

Description

local_use_cli() marks a package namespace or the environment of a running function with a special flag that instructs abort() to use cli to format error messages. This formatting happens lazily, at print-time, in various places:

• When an unexpected error is displayed to the user.

• When a captured error is printed in the console, for instance via last_error().

• When conditionMessage() is called.

cli formats messages and bullets with indentation and width-wrapping to produce a polished display of messages.

Usage

local_use_cli(..., format = TRUE, inline = FALSE, frame = caller_env())

Arguments

...	These dots are for future extensions and must be empty.
format	Whether to use cli at print-time to format messages and bullets.
inline	Whether to use cli at throw-time to format the inline parts of a message. This makes it possible to use cli interpolation and formatting with abort().
frame	A package namespace or an environment of a running function.

Usage

To use cli formatting automatically in your package:

1. Make sure run_on_load() is called from your .onLoad() hook.

2. Call on_load(local_use_cli()) at the top level of your namespace.

It is also possible to call local_use_cli() inside a running function, in which case the flag only applies within that function.

rlang documentation built on April 12, 2025, 1:13 a.m.