Document `cli.default_handler` option

[multimeric]

The existence of the cli.default_handler option is documented, and I've established that this has to be set to a function with 1 argument. Unfortunately I'm not sure how to work with this argument. It seems to be a cli_message object, which has no methods.

> str(message)
List of 4
 $ message: chr "cli message alert_warning"
 $ type   : chr "alert_warning"
 $ args   :List of 4
  ..$ text :List of 2
  .. ..$ str   : chr "<FCkNXbE-1v5FCkNXbE-1>: <FCkNXbE-1v6FCkNXbE-1>"
  .. ..$ values:<environment: 0x562267b28480> 
  .. ..- attr(*, "class")= chr "cli_glue_delay"
  ..$ id   : chr "cli-155-1"
  ..$ class: NULL
  ..$ wrap : logi FALSE
 $ pid    : int 155
 - attr(*, "class")= chr [1:2] "cli_message" "condition"
> class(message)
[1] "cli_message" "condition"`

In practice I just want to convert the message to a character vector and then save it somewhere. However this class doesn't seem to have a format() method or anything. Can we please document this class and also the cli.default_handler function?

[gaborcsardi]

I am not too eager to document cli_message and commit to its current structure.

Maybe you could use another means to record the messages, e.g. cli_fmt()?

[gaborcsardi]

Btw. ultimately cli messages will become just messages, so you could also define a global handler for messages:

msgs <- list()
globalCallingHandlers(message = function(m) msgs <<- c(msgs, list(m)))
message("hello")

hello

cli::cli_bullets(c(x = "not this", i = "but that"))

✖ not this
ℹ but that

msgs

[[1]]
<simpleMessage in message("hello"): hello
>

[[2]]
<cliMessage: ✖ not this
>

[[3]]
<cliMessage: ℹ but that
>

sapply(msgs, conditionMessage)

[1] "hello\n"                      "\033[31m✖\033[39m not this\n"
[3] "\033[36mℹ\033[39m but that\n"

cat(sapply(msgs, conditionMessage), sep = "")

hello
✖ not this
ℹ but that