This method can be typically used in format() S3 methods. Then the print() method of the class can be easily defined in terms of such a format() method. See examples below.

cli_format_method(expr, theme = getOption("cli.theme"))

Arguments

expr

Expression that calls cli_* methods, base::cat() or base::print() to format an object's printout.

theme

Theme to use for the formatting.

Value

Character vector, one element for each line of the printout.

Examples


# Let's create format and print methods for a new S3 class that
# represents the an installed R package: `r_package`

# An `r_package` will contain the DESCRIPTION metadata of the package
# and also its installation path.
new_r_package <- function(pkg) {
  tryCatch(
    desc <- packageDescription(pkg),
    warning = function(e) stop("Cannot find R package `", pkg, "`")
  )
  file <- dirname(attr(desc, "file"))
  if (basename(file) != pkg) file <- dirname(file)
  structure(
    list(desc = unclass(desc), lib = dirname(file)),
    class = "r_package"
  )
}

format.r_package <- function(x, ...) {
  cli_format_method({
    cli_h1("{.pkg {x$desc$Package}} {cli::symbol$line} {x$desc$Title}")
    cli_text("{x$desc$Description}")
    cli_ul(c(
      "Version: {x$desc$Version}",
      if (!is.null(x$desc$Maintainer)) "Maintainer: {x$desc$Maintainer}",
      "License: {x$desc$License}"
    ))
    if (!is.na(x$desc$URL)) cli_text("See more at {.url {x$desc$URL}}")
  })
}

# Now the print method is easy:
print.r_package <- function(x, ...) {
  cat(format(x, ...), sep = "\n")
}

# Try it out
new_r_package("cli")
#> $desc
#> $desc$Package
#> [1] "cli"
#> 
#> $desc$Title
#> [1] "Helpers for Developing Command Line Interfaces"
#> 
#> $desc$Version
#> [1] "3.1.0"
#> 
#> $desc$`Authors@R`
#> [1] "c(\n    person(\"Gábor\", \"Csárdi\", , \"csardi.gabor@gmail.com\", c(\"aut\", \"cre\")),\n    person(\"Hadley\", \"Wickham\", role = c(\"ctb\")),\n    person(\"Kirill\", \"Müller\", role = c(\"ctb\")),\n    person(\"RStudio\", role = \"cph\")\n    )"
#> 
#> $desc$Description
#> [1] "A suite of tools to build attractive command line interfaces\n    ('CLIs'), from semantic elements: headings, lists, alerts, paragraphs,\n    etc. Supports custom themes via a 'CSS'-like language. It also contains a\n    number of lower level 'CLI' elements: rules, boxes, trees, and\n    'Unicode' symbols with 'ASCII' alternatives. It support ANSI colors and\n    text styles as well."
#> 
#> $desc$License
#> [1] "MIT + file LICENSE"
#> 
#> $desc$URL
#> [1] "https://cli.r-lib.org, https://github.com/r-lib/cli#readme"
#> 
#> $desc$BugReports
#> [1] "https://github.com/r-lib/cli/issues"
#> 
#> $desc$RoxygenNote
#> [1] "7.1.2"
#> 
#> $desc$Depends
#> [1] "R (>= 2.10)"
#> 
#> $desc$Imports
#> [1] "glue,\nutils"
#> 
#> $desc$Suggests
#> [1] "asciicast,\ncallr,\ncovr,\ngrDevices,\nhtmltools,\nhtmlwidgets,\nknitr,\nmethods,\nmockery,\nprocessx,\nps (>= 1.3.4.9000),\nrlang,\nrmarkdown,\nrstudioapi,\nshiny,\ntestthat,\ntibble,\nwhoami,\nwithr"
#> 
#> $desc$`Config/testthat/edition`
#> [1] "3"
#> 
#> $desc$Encoding
#> [1] "UTF-8"
#> 
#> $desc$Author
#> [1] "Gábor Csárdi [aut, cre],\n  Hadley Wickham [ctb],\n  Kirill Müller [ctb],\n  RStudio [cph]"
#> 
#> $desc$Maintainer
#> [1] "Gábor Csárdi <csardi.gabor@gmail.com>"
#> 
#> $desc$Built
#> [1] "R 4.1.1; x86_64-apple-darwin17.0; 2021-10-28 11:07:16 UTC; unix"
#> 
#> attr(,"file")
#> [1] "/Users/gaborcsardi/Library/R/x86_64/4.1/library/cli/Meta/package.rds"
#> 
#> $lib
#> [1] "/Users/gaborcsardi/Library/R/x86_64/4.1/library"
#> 
#> attr(,"class")
#> [1] "r_package"

# The formatting of the output depends on the current theme:
opt <- options(cli.theme = simple_theme())
print(new_r_package("cli"))
#> 
#> ── cli ─ Helpers for Developing Command Line Interfaces ────────────────────────
#> A suite of tools to build attractive command line interfaces ('CLIs'), from
#> semantic elements: headings, lists, alerts, paragraphs, etc. Supports custom
#> themes via a 'CSS'-like language. It also contains a number of lower level
#> 'CLI' elements: rules, boxes, trees, and 'Unicode' symbols with 'ASCII'
#> alternatives. It support ANSI colors and text styles as well.
#> • Version: 3.1.0
#> • Maintainer: Gábor Csárdi <csardi.gabor@gmail.com>
#> • License: MIT + file LICENSE
#> See more at <https://cli.r-lib.org, https://github.com/r-lib/cli#readme>
options(opt)  # <- restore theme