knitr::opts_chunk$set( collapse = TRUE, comment = "#>", error = TRUE )
library(googlesheets4)
In a hidden chunk here, I "export" the internal helpers covered below.
gs4_bullets <- googlesheets4:::gs4_bullets gs4_abort <- googlesheets4:::gs4_abort abort_unsupported_conversion <- googlesheets4:::abort_unsupported_conversion bulletize <- gargle:::bulletize
Everything should be emitted by helpers in utils-ui.R
: specifically, gs4_bullets()
and, for errors, gs4_abort()
.
These helpers are wrappers around cli::cli_inform()
and cli::cli_abort()
, respectively.
gs4_bullets(c( "noindent", " " = "indent", "*" = "bullet", ">" = "arrow", "v" = "Doing good stuff for YOU the user", "x" = "Nope nope nope", "!" = "You might want to know about this", "i" = "The more you know!" ))
The helpers encourage consistent styling and make it possible to selectively silence messages coming from googlesheets4. The googlesheets4 message helpers:
rlang::inform()
, which is important because inform()
prints to standard output in interactive sessions. This means that informational messages won't have the same "look" as errors and can generally be more stylish, at least in IDEs like RStudio."googlesheets4_quiet"
option. If it's unset, the default is to show messages (unless we're testing, i.e. the environment variable TESTTHAT
is "true"
). googlesheets4_quiet = TRUE
will suppress messages. There are withr-style convenience helpers: local_gs4_quiet()
and with_gs4_quiet()
.How we use the inline classes:
.s_sheet
for the name of Google Sheet (custom).w_sheet
for the name of a worksheet (custom).range
for an A1-style range or named range (custom).code
for a column in a data frame and for reserved words, such as NULL
, TRUE
, and NA
.arg
, .fun
, .path
, .cls
, .url
. .email
for their usual purposeThese may not demo well via pkgdown, but the interactive experience is nice.
nm <- "name-of-a-Google-Sheet" gs4_bullets(c(v = "Creating new Sheet: {.s_sheet {nm}}")) nm <- "name-of-a-worksheet" gs4_bullets(c(v = "Protecting cells on sheet: {.w_sheet {nm}}")) rg <- "A3:B20" gs4_bullets(c(v = "Writing to the range: {.range {rg}}"))
Above, I don't include a period (.
) at the end of a message with the form: Description of thing: THING
.
I view it as a special case of a bullet list of simple items, which also don't get periods. (bulletize()
comes from gargle.)
gs4_bullets(c( "We're going to list some things:", bulletize(gargle::gargle_map_cli(month.abb[1:4])) ))
Other messages that are complete sentence, or at least aspire to be, do get a period.
gs4_bullets("Doing the stuff you asked me to do.") gs4_bullets(c( "You probably need to do one of these things:", "*" = "Call {.fun some_function}.", "*" = "Provide more specific input via {.arg some_argument}." ))
Most relevant cli docs:
cli's pluralization is awesome!
nm <- "name-of-a-Google-Sheet" n_new <- 1 gs4_bullets(c(v = "Adding {n_new} sheet{?s} to {.s_sheet {nm}}")) n_new <- 3 gs4_bullets(c(v = "Adding {n_new} sheet{?s} to {.s_sheet {nm}}"))
Collapsing lists of things is great! Also more pluralization.
new_sheet_names <- c("apple", "banana", "cherry") gs4_bullets(c("New sheet{?s}: {.w_sheet {new_sheet_names}}")) new_sheet_names <- "kumquat" gs4_bullets(c("New sheet{?s}: {.w_sheet {new_sheet_names}}"))
If you want to see some tricky examples of building up a message from parts, look here:
range_speedread()
Use gs4_abort()
instead of rlang::abort()
or stop()
.
So far, I'm not really using ...
to put data in the condition, but I could start when/if there's a reason to.
abort_unsupported_conversion()
is a wrapper around gs4_abort()
.
x <- structure(1, class = c("a", "b", "c")) abort_unsupported_conversion(x, to = "SheetThing")
abort_unsupported_conversion()
exists to standardize a recurring type of error message, usually encountered during development, not by end-users.
I use it a lot in the default method of an as_{to}()
generic.
There's not much to add here re: errors, now that cli::cli_abort()
exists.
Error messages are formed just like informational messages now.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.