From 4673919413c1caa4a2c4363d8334fe60fe5c7609 Mon Sep 17 00:00:00 2001 From: Indrajeet Patil Date: Sun, 21 Apr 2024 10:07:51 +0200 Subject: [PATCH 1/3] docs: Document package options --- DESCRIPTION | 1 + R/options.R | 34 ++++++++++++++++++++++++++++++++++ R/zzz.R | 2 +- _pkgdown.yaml | 1 + man/styler_options.Rd | 38 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 R/options.R create mode 100644 man/styler_options.Rd diff --git a/DESCRIPTION b/DESCRIPTION index 5fafc848c..94f6ec94d 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -69,6 +69,7 @@ Collate: 'io.R' 'nest.R' 'nested-to-tree.R' + 'options.R' 'parse.R' 'reindent.R' 'token-define.R' diff --git a/R/options.R b/R/options.R new file mode 100644 index 000000000..3ccc6f392 --- /dev/null +++ b/R/options.R @@ -0,0 +1,34 @@ +#' Package options +#' +#' These options can be set via [options()] and queried via [getOption()]. +#' For this, add a `styler.` prefix (the package name and a dot) to the option name. +#' Example: for an option `foo`, use `options(styler.foo = value)` to set it +#' and `getOption("styler.foo")` to retrieve the current value. +#' An option value of `NULL` means that the default is used. +#' +#' @usage NULL +#' @format NULL +#' +#' @name styler_options +#' +#' @examplesIf FALSE +#' getOption("styler.ignore_alignment") +#' options( +#' styler.ignore_alignment = TRUE, +#' styler.quiet = TRUE +#' ) +#' getOption("styler.ignore_alignment") +#' +#' @section Options for the styler package: +#' +#' - `styler.addins_style_transformer`: character. The name of the style transformer to use in the addins. +#' - `styler.cache_name`: character. The name of the styler cache to use. +#' - `styler.cache_root`: character. The directory where the cache files are stored. +#' - `styler.colored_print.vertical`: logical. It decides whether or not the output should be colored with +#' `prettycode::highlight()`. +#' - `styler.ignore_alignment`: logical. If `TRUE`, alignment, when detected, is ignored. +#' - `styler.ignore_start`, `styler.ignore_stop`: character. Regular expressions to ignore lines that match them. +#' - `styler.quiet`: logical. It decides whether or not to print an informative message about what the +#' function is doing. If `TRUE`, no output is printed. +#' - `styler.test_dir_writable`: logical. If `TRUE`, the package tests whether the directory is writable. +NULL diff --git a/R/zzz.R b/R/zzz.R index 00e668084..65bfd3e16 100644 --- a/R/zzz.R +++ b/R/zzz.R @@ -6,8 +6,8 @@ op <- options() op.styler <- list( styler.addins_style_transformer = "styler::tidyverse_style()", - styler.cache_root = NULL, styler.cache_name = styler_version, + styler.cache_root = NULL, styler.colored_print.vertical = TRUE, styler.ignore_alignment = FALSE, styler.ignore_start = .default_ignore_start, diff --git a/_pkgdown.yaml b/_pkgdown.yaml index ed50bc3f2..69e6d3d3b 100644 --- a/_pkgdown.yaml +++ b/_pkgdown.yaml @@ -11,6 +11,7 @@ reference: - style_pkg - style_dir - styler_addins + - styler_options - title: "Fine-tune styling" desc: "Customize style guides" - contents: diff --git a/man/styler_options.Rd b/man/styler_options.Rd new file mode 100644 index 000000000..ee3b64b3b --- /dev/null +++ b/man/styler_options.Rd @@ -0,0 +1,38 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/options.R +\name{styler_options} +\alias{styler_options} +\title{Package options} +\description{ +These options can be set via \code{\link[=options]{options()}} and queried via \code{\link[=getOption]{getOption()}}. +For this, add a \code{styler.} prefix (the package name and a dot) to the option name. +Example: for an option \code{foo}, use \code{options(styler.foo = value)} to set it +and \code{getOption("styler.foo")} to retrieve the current value. +An option value of \code{NULL} means that the default is used. +} +\section{Options for the styler package}{ + +\itemize{ +\item \code{styler.addins_style_transformer}: character. The name of the style transformer to use in the addins. +\item \code{styler.cache_name}: character. The name of the styler cache to use. +\item \code{styler.cache_root}: character. The directory where the cache files are stored. +\item \code{styler.colored_print.vertical}: logical. It decides whether or not the output should be colored with +\code{prettycode::highlight()}. +\item \code{styler.ignore_alignment}: logical. If \code{TRUE}, alignment, when detected, is ignored. +\item \code{styler.ignore_start}, \code{styler.ignore_stop}: character. Regular expressions to ignore lines that match them. +\item \code{styler.quiet}: logical. It decides whether or not to print an informative message about what the +function is doing. If \code{TRUE}, no output is printed. +\item \code{styler.test_dir_writable}: logical. If \code{TRUE}, the package tests whether the directory is writable. +} +} + +\examples{ +\dontshow{if (FALSE) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} +getOption("styler.ignore_alignment") +options( + styler.ignore_alignment = TRUE, + styler.quiet = TRUE +) +getOption("styler.ignore_alignment") +\dontshow{\}) # examplesIf} +} From b1d08155a354917fac85ad82eb2053eb8b066a3c Mon Sep 17 00:00:00 2001 From: Indrajeet Patil Date: Sun, 21 Apr 2024 10:15:26 +0200 Subject: [PATCH 2/3] also include defaults --- R/options.R | 42 ++++++++++++++++++++++++++++++++---------- man/styler_options.Rd | 35 +++++++++++++++++++++++++---------- 2 files changed, 57 insertions(+), 20 deletions(-) diff --git a/R/options.R b/R/options.R index 3ccc6f392..d299b909f 100644 --- a/R/options.R +++ b/R/options.R @@ -21,14 +21,36 @@ #' #' @section Options for the styler package: #' -#' - `styler.addins_style_transformer`: character. The name of the style transformer to use in the addins. -#' - `styler.cache_name`: character. The name of the styler cache to use. -#' - `styler.cache_root`: character. The directory where the cache files are stored. -#' - `styler.colored_print.vertical`: logical. It decides whether or not the output should be colored with -#' `prettycode::highlight()`. -#' - `styler.ignore_alignment`: logical. If `TRUE`, alignment, when detected, is ignored. -#' - `styler.ignore_start`, `styler.ignore_stop`: character. Regular expressions to ignore lines that match them. -#' - `styler.quiet`: logical. It decides whether or not to print an informative message about what the -#' function is doing. If `TRUE`, no output is printed. -#' - `styler.test_dir_writable`: logical. If `TRUE`, the package tests whether the directory is writable. +#' - `styler.addins_style_transformer`: character. +#' The name of the style transformer to use in the addins. +#' (default: `"styler::tidyverse_style()"`) +#' +#' - `styler.cache_name`: character. +#' The name of the styler cache to use. +#' (default: current styler package version) +#' +#' - `styler.cache_root`: character. +#' The directory where the cache files are stored. +#' (default: `NULL`) +#' +#' - `styler.colored_print.vertical`: logical. +#' It decides whether or not the output should be colored with `prettycode::highlight()`. +#' (default: `TRUE`) +#' +#' - `styler.ignore_alignment`: logical. +#' If `TRUE`, alignment, when detected, is ignored. +#' (default: `FALSE`) +#' +#' - `styler.ignore_start`, `styler.ignore_stop`: character. +#' Regular expressions to ignore lines that match them. +#' (default: `"styler: off"` and `"styler: on"`, respectively) +#' +#' - `styler.quiet`: logical. +#' It decides whether or not to print an informative message about what the function is doing. +#' If `TRUE`, no output is printed. +#' (default: `FALSE`) +#' +#' - `styler.test_dir_writable`: logical. +#' If `TRUE`, the package tests whether the directory is writable. +#' (default: `TRUE`) NULL diff --git a/man/styler_options.Rd b/man/styler_options.Rd index ee3b64b3b..1531f2648 100644 --- a/man/styler_options.Rd +++ b/man/styler_options.Rd @@ -13,16 +13,31 @@ An option value of \code{NULL} means that the default is used. \section{Options for the styler package}{ \itemize{ -\item \code{styler.addins_style_transformer}: character. The name of the style transformer to use in the addins. -\item \code{styler.cache_name}: character. The name of the styler cache to use. -\item \code{styler.cache_root}: character. The directory where the cache files are stored. -\item \code{styler.colored_print.vertical}: logical. It decides whether or not the output should be colored with -\code{prettycode::highlight()}. -\item \code{styler.ignore_alignment}: logical. If \code{TRUE}, alignment, when detected, is ignored. -\item \code{styler.ignore_start}, \code{styler.ignore_stop}: character. Regular expressions to ignore lines that match them. -\item \code{styler.quiet}: logical. It decides whether or not to print an informative message about what the -function is doing. If \code{TRUE}, no output is printed. -\item \code{styler.test_dir_writable}: logical. If \code{TRUE}, the package tests whether the directory is writable. +\item \code{styler.addins_style_transformer}: character. +The name of the style transformer to use in the addins. +(default: \code{"styler::tidyverse_style()"}) +\item \code{styler.cache_name}: character. +The name of the styler cache to use. +(default: current styler package version) +\item \code{styler.cache_root}: character. +The directory where the cache files are stored. +(default: \code{NULL}) +\item \code{styler.colored_print.vertical}: logical. +It decides whether or not the output should be colored with \code{prettycode::highlight()}. +(default: \code{TRUE}) +\item \code{styler.ignore_alignment}: logical. +If \code{TRUE}, alignment, when detected, is ignored. +(default: \code{FALSE}) +\item \code{styler.ignore_start}, \code{styler.ignore_stop}: character. +Regular expressions to ignore lines that match them. +(default: \code{"styler: off"} and \code{"styler: on"}, respectively) +\item \code{styler.quiet}: logical. +It decides whether or not to print an informative message about what the function is doing. +If \code{TRUE}, no output is printed. +(default: \code{FALSE}) +\item \code{styler.test_dir_writable}: logical. +If \code{TRUE}, the package tests whether the directory is writable. +(default: \code{TRUE}) } } From 040eeedce2eefa3aef826d97c8551862e5cde72d Mon Sep 17 00:00:00 2001 From: Indrajeet Patil Date: Sun, 21 Apr 2024 19:07:43 +0200 Subject: [PATCH 3/3] address feedback --- R/options.R | 8 ++++---- man/styler_options.Rd | 8 ++++---- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/R/options.R b/R/options.R index d299b909f..1625f5a1c 100644 --- a/R/options.R +++ b/R/options.R @@ -27,10 +27,10 @@ #' #' - `styler.cache_name`: character. #' The name of the styler cache to use. -#' (default: current styler package version) +#' (default: `r unlist(unname(read.dcf("DESCRIPTION")[, "Version"]), use.names = FALSE)`) #' #' - `styler.cache_root`: character. -#' The directory where the cache files are stored. +#' The directory where the cache files are stored. For more, see `help("caching")`. #' (default: `NULL`) #' #' - `styler.colored_print.vertical`: logical. @@ -38,11 +38,11 @@ #' (default: `TRUE`) #' #' - `styler.ignore_alignment`: logical. -#' If `TRUE`, alignment, when detected, is ignored. +#' If `TRUE`, alignment, when detected, is ignored. For more, see `vignette("detect-alignment")`. #' (default: `FALSE`) #' #' - `styler.ignore_start`, `styler.ignore_stop`: character. -#' Regular expressions to ignore lines that match them. +#' Regular expressions to ignore lines that match them. For more, see `help("stylerignore")`. #' (default: `"styler: off"` and `"styler: on"`, respectively) #' #' - `styler.quiet`: logical. diff --git a/man/styler_options.Rd b/man/styler_options.Rd index 1531f2648..add90dd39 100644 --- a/man/styler_options.Rd +++ b/man/styler_options.Rd @@ -18,18 +18,18 @@ The name of the style transformer to use in the addins. (default: \code{"styler::tidyverse_style()"}) \item \code{styler.cache_name}: character. The name of the styler cache to use. -(default: current styler package version) +(default: 1.10.3.9000) \item \code{styler.cache_root}: character. -The directory where the cache files are stored. +The directory where the cache files are stored. For more, see \code{help("caching")}. (default: \code{NULL}) \item \code{styler.colored_print.vertical}: logical. It decides whether or not the output should be colored with \code{prettycode::highlight()}. (default: \code{TRUE}) \item \code{styler.ignore_alignment}: logical. -If \code{TRUE}, alignment, when detected, is ignored. +If \code{TRUE}, alignment, when detected, is ignored. For more, see \code{vignette("detect-alignment")}. (default: \code{FALSE}) \item \code{styler.ignore_start}, \code{styler.ignore_stop}: character. -Regular expressions to ignore lines that match them. +Regular expressions to ignore lines that match them. For more, see \code{help("stylerignore")}. (default: \code{"styler: off"} and \code{"styler: on"}, respectively) \item \code{styler.quiet}: logical. It decides whether or not to print an informative message about what the function is doing.