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] "2.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 )" #> #> $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 integrates with the\n 'crayon' package to support 'ANSI' terminal colors." #> #> $desc$License #> [1] "MIT + file LICENSE" #> #> $desc$LazyData #> [1] "true" #> #> $desc$URL #> [1] "https://github.com/r-lib/cli#readme" #> #> $desc$BugReports #> [1] "https://github.com/r-lib/cli/issues" #> #> $desc$RoxygenNote #> [1] "7.1.1" #> #> $desc$Roxygen #> [1] "list(markdown = TRUE)" #> #> $desc$Depends #> [1] "R (>= 2.10)" #> #> $desc$Imports #> [1] "assertthat,\ncrayon (>= 1.3.4),\nglue,\nmethods,\nutils,\nfansi" #> #> $desc$Suggests #> [1] "callr,\ncovr,\nhtmlwidgets,\nknitr,\nmockery,\nps (>= 1.3.4.9000),\nrmarkdown,\nrstudioapi,\nprettycode (>= 1.1.0),\ntestthat,\nwithr" #> #> $desc$Encoding #> [1] "UTF-8" #> #> $desc$Author #> [1] "Gábor Csárdi [aut, cre],\n Hadley Wickham [ctb],\n Kirill Müller [ctb]" #> #> $desc$Maintainer #> [1] "Gábor Csárdi <csardi.gabor@gmail.com>" #> #> $desc$Built #> [1] "R 4.0.3; ; 2020-10-16 08:59:58 UTC; unix" #> #> attr(,"file") #> [1] "/Users/runner/work/_temp/Library/cli/Meta/package.rds" #> #> $lib #> [1] "/Users/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 ── ─ ────────────────────────────────────────────────────────────────────
#> 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 integrates with the 'crayon' package to support 'ANSI' #> terminal colors.
#> ● Version: 2.1.0
#> ● Maintainer: Gábor Csárdi <csardi.gabor@gmail.com>
#> ● License: MIT + file LICENSE
#> See more at <https://github.com/r-lib/cli#readme>
#>
options(opt) # <- restore theme