Skip to content

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.

Usage

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.6.3"
#> 
#> $desc$`Authors@R`
#> [1] "c(\n    person(\"Gábor\", \"Csárdi\", , \"csardi.gabor@gmail.com\", role = c(\"aut\", \"cre\")),\n    person(\"Hadley\", \"Wickham\", role = \"ctb\"),\n    person(\"Kirill\", \"Müller\", role = \"ctb\"),\n    person(\"Salim\", \"Brüggemann\", , \"salim-b@pm.me\", role = \"ctb\",\n           comment = c(ORCID = \"0000-0002-5329-5987\")),\n    person(\"Posit Software, PBC\", role = c(\"cph\", \"fnd\"))\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\n    contains a number of lower level 'CLI' elements: rules, boxes, trees,\n    and 'Unicode' symbols with 'ASCII' alternatives. It support ANSI\n    colors and text styles as well."
#> 
#> $desc$License
#> [1] "MIT + file LICENSE"
#> 
#> $desc$URL
#> [1] "https://cli.r-lib.org, https://github.com/r-lib/cli"
#> 
#> $desc$BugReports
#> [1] "https://github.com/r-lib/cli/issues"
#> 
#> $desc$Depends
#> [1] "R (>= 3.4)"
#> 
#> $desc$Imports
#> [1] "utils"
#> 
#> $desc$Suggests
#> [1] "callr, covr, crayon, digest, glue (>= 1.6.0), grDevices,\nhtmltools, htmlwidgets, knitr, methods, mockery, processx, ps\n(>= 1.3.4.9000), rlang (>= 1.0.2.9003), rmarkdown, rprojroot,\nrstudioapi, testthat, tibble, whoami, withr"
#> 
#> $desc$`Config/Needs/website`
#> [1] "r-lib/asciicast, bench, brio, cpp11, decor, desc,\nfansi, prettyunits, sessioninfo, tidyverse/tidytemplate,\nusethis, vctrs"
#> 
#> $desc$`Config/testthat/edition`
#> [1] "3"
#> 
#> $desc$Encoding
#> [1] "UTF-8"
#> 
#> $desc$RoxygenNote
#> [1] "7.2.3"
#> 
#> $desc$NeedsCompilation
#> [1] "yes"
#> 
#> $desc$Packaged
#> [1] "2024-06-23 12:08:19 UTC; runner"
#> 
#> $desc$Author
#> [1] "Gábor Csárdi [aut, cre],\n  Hadley Wickham [ctb],\n  Kirill Müller [ctb],\n  Salim Brüggemann [ctb] (<https://orcid.org/0000-0002-5329-5987>),\n  Posit Software, PBC [cph, fnd]"
#> 
#> $desc$Maintainer
#> [1] "Gábor Csárdi <csardi.gabor@gmail.com>"
#> 
#> $desc$Built
#> [1] "R 4.4.1; x86_64-pc-linux-gnu; 2024-06-23 12:08:20 UTC; unix"
#> 
#> $desc$RemotePkgRef
#> [1] "local::."
#> 
#> $desc$RemoteType
#> [1] "local"
#> 
#> attr(,"file")
#> [1] "/home/runner/work/_temp/Library/cli/Meta/package.rds"
#> 
#> $lib
#> [1] "/home/runner/work/_temp/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.6.3
#> • 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>
options(opt)  # <- restore theme