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..1625f5a1c --- /dev/null +++ b/R/options.R @@ -0,0 +1,56 @@ +#' 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. +#' (default: `"styler::tidyverse_style()"`) +#' +#' - `styler.cache_name`: character. +#' The name of the styler cache to use. +#' (default: `r unlist(unname(read.dcf("DESCRIPTION")[, "Version"]), use.names = FALSE)`) +#' +#' - `styler.cache_root`: character. +#' The directory where the cache files are stored. For more, see `help("caching")`. +#' (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. For more, see `vignette("detect-alignment")`. +#' (default: `FALSE`) +#' +#' - `styler.ignore_start`, `styler.ignore_stop`: character. +#' Regular expressions to ignore lines that match them. For more, see `help("stylerignore")`. +#' (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/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..add90dd39 --- /dev/null +++ b/man/styler_options.Rd @@ -0,0 +1,53 @@ +% 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. +(default: \code{"styler::tidyverse_style()"}) +\item \code{styler.cache_name}: character. +The name of the styler cache to use. +(default: 1.10.3.9000) +\item \code{styler.cache_root}: character. +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. 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. 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. +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}) +} +} + +\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} +}