Merge pull request #560 from lorenzwalthert/stylerignore

- Ignore certain lines when styling (#560).

Author: lorenzwalthert

DESCRIPTION

@@ -73,6 +73,7 @@ Collate:
     'set-assert-args.R'
     'style-guides.R'
     'styler.R'
+    'stylerignore.R'
     'testing-mocks.R'
     'testing-public-api.R'
     'testing.R'

NEWS.md

@@ -1,8 +1,11 @@
 # styler 1.2.0.9000
 
+* ignore certain lines using `# styler: off` and `#styler: on` or custom 
+  markers, see `help("stylerignore")` (#560).
+
 * function documentation now contains many more linebreaks due to roxygen2 
   update to version 7.0.1 (#566).
-
+  
 # styler 1.2.0
 
 ## Breaking changes

R/detect-alignment-utils.R

@@ -101,6 +101,7 @@ alignment_serialize_column <- function(relevant_pd_by_line, column) {
 #'
 #' @inheritParams alignment_serialize_column
 #' @inheritParams alignment_col1_is_named
+#' @keywords internal
 alignment_serialize_line <- function(relevant_pd_by_line, column) {
   # TODO
   # better also add lover bound for column. If you already checked up to comma 2,

R/detect-alignment.R

@@ -24,6 +24,7 @@
 #'
 #' @importFrom purrr map_int map_lgl map compact
 #' @importFrom rlang seq2
+#' @keywords internal
 #' @examples
 #' library("magrittr")
 #' transformers <- tidyverse_style()

R/environments.R

@@ -46,5 +46,17 @@ parser_version_find <- function(pd) {
 }
 
 
-
+#' The elements that are added to this environment are:
+#'
+#' @details
+#' * `parser_version`: Needed to dispatch between parser versions, see
+#'   [parser_version_set()] for details.
+#' * `stylerignore`: A tibble with parse data containing tokens that fall within
+#'   a stylerignore sequence. This is used after serializing the flattened
+#'   parse table to apply the initial formatting to these tokens. See
+#'   [stylerignore] for details.
+#' * `any_stylerignore`: Whether there is any stylerignore marker. The idea is
+#'   to check early in the runtime if this is the case and then if so, take
+#'   as many short-cuts as possible. See [stylerignore] for details.
+#' @keywords internal
 env_current <- rlang::new_environment(parent = rlang::empty_env())

R/nest.R

@@ -10,7 +10,10 @@
 compute_parse_data_nested <- function(text) {
   parse_data <- tokenize(text) %>%
     add_terminal_token_before() %>%
-    add_terminal_token_after()
+    add_terminal_token_after() %>%
+    add_stylerignore()
+
+  env_add_stylerignore(parse_data)
 
   parse_data$child <- rep(list(NULL), length(parse_data$text))
   pd_nested <- parse_data %>%
@@ -21,6 +24,57 @@ compute_parse_data_nested <- function(text) {
   pd_nested
 }
 
+#' Turn off styling for parts of the code
+#'
+#' Using stylerignore markers, you can temporarily turn off styler. See a
+#' few illustrative examples below.
+#' @details
+#' Styling is on by default when you run styler.
+#' - To mark the start of a sequence where you want to turn styling off, use
+#'   `# styler: off`.
+#' - To mark the end of this sequence, put `# styler: on` in your code. After
+#'   that line, styler will again format your code.
+#' - To ignore an inline statement (i.e. just one line), place `# styler: off`
+#'   at the end of the line. Note that inline statements cannot contain other
+#'   comments apart from the marker, i.e. a line like
+#'   `1 # comment # styler: off` won't be ignored.
+#'
+#' To use something else as start and stop markers, set the R options
+#' `styler.ignore_start` and
+#' `styler.ignore_stop` using [options()]. If you want these
+#' settings to persist over mulitple R sessions, consider setting them in your
+#' R profile, e.g. with `usethis::edit_rprofile()`.
+#' @name stylerignore
+#' @examples
+#' # as long as the order of the markers is correct, the lines are ignored.
+#' style_text(
+#'   "
+#'   1+1
+#'   # styler: off
+#'   1+1
+#'   # styler: on
+#'   1+1
+#'   "
+#')
+#'
+#' # if there is a stop marker before a start marker, styler won't be able
+#' # to figure out which lines you want to ignore and won't ignore anything,
+#' # issuing a warning.
+#' \dontrun{
+#' style_text(
+#'   "
+#'   1+1
+#'   # styler: off
+#'   1+1
+#'   # styler: off
+#'   1+1
+#'   "
+#')
+#'}
+#'
+NULL
+
+
 #' Enhance the mapping of text to the token "SPECIAL"
 #'
 #' Map text corresponding to the token "SPECIAL" to a (more) unique token

R/serialize.R

@@ -1,11 +1,12 @@
 #' Serialize flattened parse data
 #'
 #' Collapses a flattened parse table into character vector representation.
-#' @param flattened_pd A flattened parse table.
+#' @inheritParams apply_stylerignore
 #' @param start_line The line number on which the code starts.
 #' @keywords internal
 serialize_parse_data_flattened <- function(flattened_pd, start_line = 1) {
   flattened_pd$lag_newlines[1] <- start_line - 1
+  flattened_pd <- apply_stylerignore(flattened_pd)
   res <- with(
     flattened_pd,
     paste0(

R/stylerignore.R

@@ -0,0 +1,116 @@
+#' Add positional information of token to next terminal
+#'
+#' This is needed because at serialization time, we also have terminals only
+#' and positional argument of non-terminals were already propagated to terminals
+#' with [context_to_terminals()].
+#' @inheritParams add_stylerignore
+#' @keywords internal
+env_add_stylerignore <- function(pd_flat) {
+  if (!env_current$any_stylerignore) {
+    env_current$stylerignore <- pd_flat[0, ]
+    return()
+  }
+  pd_flat_temp <- pd_flat[pd_flat$terminal, ] %>%
+    default_style_guide_attributes()
+  pd_flat_temp$lag_newlines <- pd_flat_temp$lag_newlines
+  pd_flat_temp$lag_spaces <- lag(pd_flat_temp$spaces, default = 0)
+  is_terminal_to_ignore <- pd_flat_temp$terminal & pd_flat_temp$stylerignore
+  env_current$stylerignore <- pd_flat_temp[is_terminal_to_ignore, ]
+}
+
+#' Adds the stylerignore column
+#'
+#' If a token should be ignored, the column is set to `TRUE`,
+#' otherwise to `FALSE`.
+#' @details
+#' A token is ignored iff one of the two conditions hold:
+#'
+#' - it falls between a start and a stop marker whereas the markers are on
+#'   their own line. Which tokens are recognized as markers is controlled with
+#'   the R options `styler.ignore_start` and `styler.ignore_stop`.
+#' - it is not a comment, but the last token on the line is a marker.
+#'
+#' See examples in [stylerignore].
+#' @param pd_flat A parse table.
+#' @keywords internal
+add_stylerignore <- function(pd_flat) {
+  parse_text <- trimws(pd_flat$text)
+  start_candidate <- parse_text == option_read("styler.ignore_start")
+  pd_flat$stylerignore <- rep(FALSE, length(start_candidate))
+  env_current$any_stylerignore <- any(start_candidate)
+  if (!env_current$any_stylerignore) {
+    return(pd_flat)
+  }
+  pd_flat_terminals <- pd_flat[pd_flat$terminal, ]
+  pd_flat_lat_line1 <- lag(pd_flat$line2, default = 0)
+  on_same_line <- pd_flat$line1 == pd_flat_lat_line1
+  cumsum_start <- cumsum(start_candidate & !on_same_line)
+  cumsum_stop <- cumsum(parse_text == option_read("styler.ignore_stop"))
+  pd_flat$indicator_off <- cumsum_start + cumsum_stop
+  is_invalid <- cumsum_start - cumsum_stop < 0 | cumsum_start - cumsum_stop > 1
+  if (any(is_invalid)) {
+    warn(paste0(
+      "Invalid stylerignore sequences found, potentially ignoring some of the ",
+      "markers set.\nSee `help(\"stylerignore\", \"styler\")`."
+    ))
+  }
+
+  to_ignore <- as.logical(pd_flat$indicator_off %% 2)
+  to_ignore[is_invalid] <- FALSE
+  single_lines_to_ignore <- pd_flat$line1[start_candidate & on_same_line]
+  to_ignore[pd_flat$line1 %in% single_lines_to_ignore] <- TRUE
+  pd_flat$indicator_off <- NULL
+  pd_flat[to_ignore & pd_flat$terminal, "stylerignore"] <- TRUE
+  pd_flat
+}
+
+#' Ensure correct positional information for stylerignore expressions
+#'
+#' @param flattened_pd A flattened parse table.
+#' @details
+#' * Get the positional information for tokens with a stylerignore tag from
+#'   `env_current`, which recorded that information from the input text.
+#' * Replace the computed lag_newlines and lag_spaces information in the parse
+#'   table with this information.
+#' @keywords internal
+apply_stylerignore <- function(flattened_pd) {
+  if (!env_current$any_stylerignore) {
+    return(flattened_pd)
+  }
+  pos_ids <- env_current$stylerignore$pos_id
+  colnames_required_apply_stylerignore <- c(
+    "pos_id", "lag_newlines", "lag_spaces", "text"
+  )
+  flattened_pd <- merge(
+    flattened_pd,
+    env_current$stylerignore[, colnames_required_apply_stylerignore],
+    by = "pos_id", all.x = TRUE
+  ) %>%
+    as_tibble()
+  flattened_pd %>%
+    stylerignore_consolidate_col("lag_newlines") %>%
+    stylerignore_consolidate_col("lag_spaces") %>%
+    stylerignore_consolidate_col("text")
+}
+
+#' Consolidate columns after a merge
+#'
+#' After [base::merge()], all non-id columns that were present in `x` and `y`
+#' do get a suffix `.x` and `.y`. If the `y` value is missing, use the `x`
+#' value (because the information for this token was not stylerignored),
+#' otherwise the `y` value (i.e. the styled value).
+#' @param col A string indicating the name of the column that should be
+#'   consolidated.
+#' @inheritParams apply_stylerignore
+#' @keywords internal
+stylerignore_consolidate_col <- function(flattened_pd, col) {
+  col_x <- paste0(col, ".x")
+  col_y <- paste0(col, ".y")
+  flattened_pd[[col]] <- ifelse(is.na(flattened_pd[[col_y]]),
+    flattened_pd[[col_x]],
+    flattened_pd[[col_y]]
+  )
+  flattened_pd[[col_x]] <- NULL
+  flattened_pd[[col_y]] <- NULL
+  flattened_pd
+}

R/token-create.R

@@ -30,7 +30,8 @@ create_tokens <- function(tokens,
                           indention_ref_pos_ids = NA,
                           indents = 0,
                           terminal = TRUE,
-                          child = NULL) {
+                          child = NULL,
+                          stylerignore = FALSE) {
   len_text <- length(texts)
   new_tibble(
     list(
@@ -48,7 +49,8 @@ create_tokens <- function(tokens,
     multi_line = rep(FALSE, len_text),
     indention_ref_pos_id = indention_ref_pos_ids,
     indent = indents,
-    child = rep(list(child), len_text)
+    child = rep(list(child), len_text),
+    stylerignore = stylerignore
   ),
     nrow = len_text
   )

R/utils.R

@@ -59,3 +59,19 @@ calls_sys <- function(sys_call, ...) {
     error <- system(sys_call, ...)
   }
 }
+
+#' Get the value of an option
+#'
+#' Basically a `getOptions()` that fails fast by default.
+#' @inheritParams base::getOption
+#' @param error_if_not_found Whether or not an error should be returned if the
+#'   option was not set.
+#' @keywords internal
+option_read <- function(x, default = NULL, error_if_not_found = TRUE) {
+  if (x %in% names(options()) | !error_if_not_found) {
+    getOption(x, default)
+  } else {
+    rlang::abort(paste("R option", x, "most be set."))
+  }
+
+}

R/zzz.R

@@ -2,7 +2,9 @@
   backports::import(pkgname, "trimws")
   op <- options()
   op.styler <- list(
-    styler.colored_print.vertical = TRUE
+    styler.colored_print.vertical = TRUE,
+    styler.ignore_start = "# styler: off",
+    styler.ignore_stop = "# styler: on"
   )
   toset <- !(names(op.styler) %in% names(op))
   if (any(toset)) options(op.styler[toset])