diff --git a/NAMESPACE b/NAMESPACE index 99525aa52..65ff31204 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -129,6 +129,7 @@ export(num) export(obj_sum) export(pillar) export(pillar_component) +export(pillar_options) export(pillar_shaft) export(set_char_opts) export(set_num_opts) diff --git a/R/options.R b/R/options.R index bac6e24c8..cfe6676ce 100644 --- a/R/options.R +++ b/R/options.R @@ -2,30 +2,37 @@ #' #' Options that affect display of tibble-like output. #' -#' These options can be set via [options()] and queried via [getOption()]. -#' For this, add a `pillar.` prefix (the package name and a dot) to the option name. -#' Example: for an option `foo`, use `options(pillar.foo = value)` to set it -#' and `getOption("pillar.foo")` to retrieve the current value. -#' An option value of `NULL` means that the default is used. +#' All options are available via the `pillar_options` list. +#' The elements of this list are combined getter/setter functions. +#' Calling a function without arguments returns the current value, +#' by providing an argument the current value is set and the old value +#' is returned, invisibly. +#' Setting `local = TRUE` enables the option for the duration of the +#' current stack frame via [rlang::local_options()]. #' -#' @format NULL +#' These options can also be set via [options()] and queried via [getOption()]. +#' For this, add a `pillar.` prefix (the package name and a dot) to the option name. +#' Example: for an option `foo`, +#' `pillar_options$foo(value)` is equivalent to +#' `options(pillar.foo = value)`. #' +#' @export #' @examples #' # Default setting: -#' getOption("pillar.sigfig") +#' pillar_options$sigfig() #' pillar(1.234567) #' #' # Change for the duration of the session: -#' old <- options(pillar.sigfig = 6) +#' old <- pillar_options$sigfig(6) #' pillar(1.234567) #' #' # Change back to the original value: -#' options(old) +#' pillar_options$sigfig(old) #' pillar(1.234567) #' #' # Local scope: #' local({ -#' rlang::local_options(pillar.sigfig = 6) +#' pillar_options$sigfig(6, local = TRUE) #' pillar(1.234567) #' }) #' pillar(1.234567) diff --git a/_pkgdown.yml b/_pkgdown.yml index 6a0473c93..094e75b71 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -79,6 +79,7 @@ navbar: development: mode: auto + destination: options authors: Kirill Müller: diff --git a/man/pillar_options.Rd b/man/pillar_options.Rd index c601a9dfc..8db815062 100644 --- a/man/pillar_options.Rd +++ b/man/pillar_options.Rd @@ -4,6 +4,9 @@ \name{pillar_options} \alias{pillar_options} \title{Package options} +\format{ +An object of class \code{list} of length 14. +} \usage{ pillar_options } @@ -11,11 +14,19 @@ pillar_options Options that affect display of tibble-like output. } \details{ -These options can be set via \code{\link[=options]{options()}} and queried via \code{\link[=getOption]{getOption()}}. +All options are available via the \code{pillar_options} list. +The elements of this list are combined getter/setter functions. +Calling a function without arguments returns the current value, +by providing an argument the current value is set and the old value +is returned, invisibly. +Setting \code{local = TRUE} enables the option for the duration of the +current stack frame via \code{\link[rlang:local_options]{rlang::local_options()}}. + +These options can also be set via \code{\link[=options]{options()}} and queried via \code{\link[=getOption]{getOption()}}. For this, add a \code{pillar.} prefix (the package name and a dot) to the option name. -Example: for an option \code{foo}, use \code{options(pillar.foo = value)} to set it -and \code{getOption("pillar.foo")} to retrieve the current value. -An option value of \code{NULL} means that the default is used. +Example: for an option \code{foo}, +\code{pillar_options$foo(value)} is equivalent to +\code{options(pillar.foo = value)}. } \section{Options for the pillar package}{ @@ -77,20 +88,20 @@ and that the column headings correspond to the correct columns. \examples{ # Default setting: -getOption("pillar.sigfig") +pillar_options$sigfig() pillar(1.234567) # Change for the duration of the session: -old <- options(pillar.sigfig = 6) +old <- pillar_options$sigfig(6) pillar(1.234567) # Change back to the original value: -options(old) +pillar_options$sigfig(old) pillar(1.234567) # Local scope: local({ - rlang::local_options(pillar.sigfig = 6) + pillar_options$sigfig(6, local = TRUE) pillar(1.234567) }) pillar(1.234567)