usethis-ui.Rmd

---
title: "From usethis::ui functions to cli"
author: "Gábor Csárdi"
date: "`r Sys.Date()`"
description: >
  Transition from usethis to cli.
output:
  rmarkdown::html_document:
    toc: true
    toc_depth: 2
editor_options: 
  markdown: 
    wrap: sentence
---

```{r, include = FALSE, cache = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  out.width = "100%",
  cache = TRUE
)
asciicast::init_knitr_engine(
  echo = TRUE,
  echo_input = FALSE,
  startup = quote({
    library(cli)
    library(usethis)
    set.seed(1)
  })
)
```

# Introduction

```{r setup}
library(cli)
library(usethis)
```

We'll show how to transition from the `usethis::ui_*` functions to cli 2.0.0.

# How to

## `usethis::ui_code()`

### Usage

    usethis::ui_code(x)

### Example

```{asciicast}
ui_todo("Redocument with {ui_code('devtools::document()')}")
```

### With cli 

In general inline code formatting can be done with inline styles in cli.
The default theme has a `"code"` class, but it also one for functions, so
this can be either of:

```{asciicast}
cli_ul("Redocument with {.code devtools::document()}")
```

```{asciicast}
cli_ul("Redocument with {.fun devtools::document}")
```

## `usethis::ui_code_block()`

### Usage

    usethis::ui_code_block(x, copy = interactive(), .envir = parent.frame())

### Example

```{asciicast, asciicast_rows = length(format(cli::cli_code)) + 2}
ui_code_block("{format(cli_code)}")
```

### With cli

`cli_code()` produces similar output and it also syntax highlight R code:

```{asciicast}
cli_code(format(cli_code))
```

However, cli does not copy stuff to the clipboard, so this has to be done
separately.

Another difference is that it also does not run glue substitutions on the
code text, so if you want that to happen you'll need to do that before the 
cli call.

## `usethis::ui_done()`

### Usage

    usethis::ui_done(x, .envir = parent.frame())

### Example

```{asciicast}
name <- "VignetteBuilder"
value <- "knitr, rmarkdown"
ui_done("Setting {ui_field(name)} field in DESCRIPTION to {ui_value(value)}")
```

### With cli

This is probably closest to `cli_alert_success()`:

```{asciicast}
cli_alert_success("Setting {.field {name}} field in DESCRIPTION to {.val {value}}")
```

If you want to handle success and failure, then maybe the `cli_process_*()`
functions are a better fit:

```{asciicast}
#| asciicast_at = "all",
#| asciicast_end_wait = 5,
#| asciicast_cursor = FALSE
tryCatch({
    cli_process_start("Setting {.field {name}} field in DESCRIPTION to {.val {value}}")
    Sys.sleep(1) # <- do the task here, we just sleep
    cli_process_done() },
  error = function(err) {
    cli_process_failed()
    cli_alert_danger("Failed to ...")
  }
)
```

## `usethis::ui_field()`

### Usage

    usethis::ui_field(x)

### Example

```{asciicast}
name <- "VignetteBuilder"
value <- "knitr, rmarkdown"
ui_done("Setting {ui_field(name)} field in DESCRIPTION to {ui_value(value)}")
```

### With cli

cli has a `"field"` class for inline styling:

```{asciicast}
cli_alert_success("Setting {.field {name}} field in DESCRIPTION to {.val {value}}")
```

Just like `usethis::ui_field()` and similar usethis functions, cli collapses
inline vectors, before styling:

```{asciicast}
name <- c("Depends", "Imports", "Suggests")
ui_done("Setting the {ui_field(name)} field(s) in DESCRIPTION")
```

```{asciicast}
cli_alert_success("Setting the {.field {name}} field{?s} in DESCRIPTION")
```

cli also helps you with the correct pluralization:

```{asciicast}
name <- "Depends"
cli_alert_success("Setting the {.field {name}} field{?s} in DESCRIPTION")
```

## `usethis::ui_info()`

### Usage

    usethis::ui_info((x, .envir = parent.frame())

### Example

```{asciicast}
ui_info("No labels need renaming")
```

### With cli

This is simply `cli_alert_info()`:

```{asciicast}
cli_alert_info("No labels need renaming")
```

## `usethis::ui_line()`

### Usage

    usethis::ui_line(x, .envir = parent.frame())

### Example

```{asciicast}
ui_line("No matching issues/PRs found.")
```

### With cli

This is just a line of text, so `cli_text()` is fine for this.
One difference is that `cli_text()` will automatically wrap the long lines.

```{asciicast}
cli_text("No matching issues/PRs found.")
```

## `usethis::ui_nope()`

### Usage

    ui_nope(x, .envir = parent.frame())

### With cli

cli does not support user input currently, so this has to stay in usethis.

## `usethis::ui_oops()`

### Usage

    usethis::ui_oops(x, .envir = parent.frame())

### Example

```{asciicast}
ui_oops("Can't validate token. Is the network reachable?")
```

### With cli

This is mostly just `cli_alert_danger()`, but for see also the
`cli_process_*()` alternatives at `usethis::ui_done()`.

## `usethis::ui_path()`

### Usage

    usethis::ui_path(x, base = NULL)

### Example

`ui_path()` formats paths as relative to the project or the supplied base
directory, and also appends a `/` to directories.

```{asciicast}
logo_path <- file.path("man", "figures", "logo.svg")
img <- "/tmp/some-image.svg"
ui_done("Copied {ui_path(img)} to {ui_path(logo_path)}")
```

### With cli

cli does not do any of these, but it does have inline markup for files and
paths:

```{asciicast}
cli_alert_success("Copied {.file {img}} to {.file {logo_path}}")
```

## `usethis::ui_stop()`

### Usage

    usethis::ui_stop(x, .envir = parent.frame())

### Example

`ui_stop()` does glue substitution on the string, and then calls `stop()` to
throw an error.

```{asciicast}
#| asciicast_rows = 2
ui_stop("Could not copy {ui_path(img)} to  {ui_path(logo_path)}, file already exists")
```

### With cli

`cli_abort()` does the same and is formatted using `cli_bullets()`.

```{asciicast}
cli_abort(c(
  "Could not copy {.file {img}} to {.file {logo_path}}, file already exists",
  "i" = "You can set {.arg overwrite = TRUE} to avoid this error"
  ))
```

## `usethis::ui_todo()`

### Usage

    usethis::ui_todo(x, .envir = parent.frame())

### Example

```{asciicast}
ui_todo("Redocument with {ui_code('devtools::document()')}")
```

### With cli

This is a bullet, so either `cli_ul()` or `cli_alert_info()` should be
appropriate:

```{asciicast}
cli_ul("Redocument with {.fun devtools::document}")
```

## `usethis::ui_value()`

### Usage

    usethis::ui_value(x)

### Example

```{asciicast}
name <- "VignetteBuilder"
value <- "knitr, rmarkdown"
ui_done("Setting {ui_field(name)} field in DESCRIPTION to {ui_value(value)}")
```

### With cli

The `"value"` inline class is appropriate for this.

```{asciicast}
cli_alert_success("Setting {.field {name}} field in DESCRIPTION to {.val {value}}")
```

## `usethis::ui_warn()`

### Usage

    usethis::ui_warn(x, .envir = parent.frame())

### Example

`ui_warn()` does glue substitution on the string, and then calls `warning()` to throw a warning.

```{asciicast}
#| asciicast_rows = 2
ui_warn("Could not copy {ui_path(img)} to  {ui_path(logo_path)}, file already exists")
```

### With cli

`cli_warn()` does the same and is formatted using `cli_bullets()`.

```{asciicast}
cli_warn(c(
  "Could not copy {.file {img}} to {.file {logo_path}}, file already exists",
  "i" = "You can set {.arg overwrite = TRUE} to avoid this warning"
  ))
```

## `usethis::ui_yeah()`

### Usage

    ui_yeah(x, .envir = parent.frame())

### With cli

cli does not support user input currently, so this has to stay in usethis.