Merge pull request #298 from lorenzwalthert/r-1.0.0

- R 1.0.0 (into r-1.0.0 instead of master) (#298).

Author: lorenzwalthert

API

@@ -2,7 +2,8 @@
 
 ## Exported functions
 
-create_style_guide(initialize = initialize_attributes, line_break = NULL, space = NULL, token = NULL, indention = NULL, use_raw_indention = FALSE, reindention = tidyverse_reindention())
+create_style_guide(initialize = default_style_guide_attributes, line_break = NULL, space = NULL, token = NULL, indention = NULL, use_raw_indention = FALSE, reindention = tidyverse_reindention())
+default_style_guide_attributes(pd_flat)
 specify_math_token_spacing(zero = NULL, one = c("'+'", "'-'", "'*'", "'/'", "'^'"))
 specify_reindention(regex_pattern = NULL, indention = 0, comments_only = TRUE)
 style_dir(path = ".", ..., style = tidyverse_style, transformers = style(...), filetype = "R", recursive = TRUE, exclude_files = NULL)
@@ -12,7 +13,3 @@ style_text(text, ..., style = tidyverse_style, transformers = style(...))
 tidyverse_math_token_spacing()
 tidyverse_reindention()
 tidyverse_style(scope = "tokens", strict = TRUE, indent_by = 2, start_comments_with_one_space = FALSE, reindention = tidyverse_reindention(), math_token_spacing = tidyverse_math_token_spacing())
-
-## Foreign S3 methods
-
-print.vertical(x, ...)

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: styler
-Title: Non-Invasive Pretty Printing of R code
+Title: Non-Invasive Pretty Printing of R Code
 Version: 1.0.0
 Authors@R: c(person("Kirill", "Müller", role = c("aut"), email = "[email protected]"),
   person("Lorenz", "Walthert", role = c("cre", "aut"), email = "[email protected]"))

NAMESPACE

@@ -2,6 +2,7 @@
 
 S3method(print,vertical)
 export(create_style_guide)
+export(default_style_guide_attributes)
 export(specify_math_token_spacing)
 export(specify_reindention)
 export(style_dir)

NEWS.md

@@ -1,12 +1,71 @@
-## styler 0.1.0 (2017-12-05)
-
-create_style_guide(initialize = initialize_attributes, line_break = NULL, space = NULL, token = NULL, indention = NULL, use_raw_indention = FALSE, reindention = tidyverse_reindention())
-specify_math_token_spacing(zero = NULL, one = c("'+'", "'-'", "'*'", "'/'", "'^'"))
-specify_reindention(regex_pattern = NULL, indention = 0, comments_only = TRUE)
-style_dir(path = ".", ..., style = tidyverse_style, transformers = style(...), filetype = "R", recursive = TRUE, exclude_files = NULL)
-style_file(path, ..., style = tidyverse_style, transformers = style(...))
-style_pkg(pkg = ".", ..., style = tidyverse_style, transformers = style(...), filetype = "R", exclude_files = "R/RcppExports.R")
+## styler 1.0.0 (2017-12-05)
+
+Initial release.
+
+### stylers
+These are functions used to style code. They style a directory, a whole package,
+a file or a string.
+```
+style_dir(path = ".", 
+  ..., style = tidyverse_style, transformers = style(...), 
+  filetype = "R", recursive = TRUE, exclude_files = NULL
+)
+
+style_pkg(pkg = ".", 
+  ..., style = tidyverse_style, transformers = style(...), filetype = "R", 
+  exclude_files = "R/RcppExports.R"
+)
+
+
+style_file(path, 
+  ..., style = tidyverse_style, transformers = style(...)
+)
+
 style_text(text, ..., style = tidyverse_style, transformers = style(...))
-tidyverse_math_token_spacing()
+```
+
+### style guides
+These functions are the style guides implemented.
+```
+tidyverse_style(
+  scope = "tokens", 
+  strict = TRUE, 
+  indent_by = 2, 
+  start_comments_with_one_space = FALSE, 
+  reindention = tidyverse_reindention(), 
+  math_token_spacing = tidyverse_math_token_spacing()
+)
 tidyverse_reindention()
-tidyverse_style(scope = "tokens", strict = TRUE, indent_by = 2, start_comments_with_one_space = FALSE, reindention = tidyverse_reindention(), math_token_spacing = tidyverse_math_token_spacing())
+tidyverse_math_token_spacing())
+```
+
+### style guide creators
+This function is used to create a style guide.
+```
+create_style_guide(
+  initialize = default_style_guide_attributes, 
+  line_break = NULL, 
+  space = NULL, 
+  token = NULL, 
+  indention = NULL, 
+  use_raw_indention = FALSE, 
+  reindention = tidyverse_reindention()
+)
+```
+
+### Helpers
+These are helper functions used to specify the style guides in use.
+
+```
+specify_math_token_spacing(
+  zero = NULL, 
+  one = c("'+'", "'-'", "'*'", "'/'", "'^'")
+)
+
+specify_reindention(
+  regex_pattern = NULL, 
+  indention = 0, 
+  comments_only = TRUE
+)
+initialize_default_attributes(pd_flat)
+```

R/indent.R

@@ -1,7 +1,7 @@
 #' Update indention information of parse data
 #'
 #' @param pd A nested or flat parse table that is already enhanced with
-#'   line break and space information via [initialize_attributes()].
+#'   line break and space information via [default_style_guide_attributes()].
 #' @param indent_by How many spaces should be added after the token of interest.
 #' @param token The token the indention should be based on.
 #' @name update_indention

R/initialize.R

@@ -1,10 +1,15 @@
-#' Enrich parse table with space and line break information
+#' Intialize default style guide attributes
 #'
-#' This function computes difference (as column and line difference) between two
-#'   entries in the parse table and adds this information to the table.
+#' This function initialises and removes various variables from the parse
+#' table.
 #' @param pd_flat A parse table.
 #' @importFrom utils tail
-initialize_attributes <- function(pd_flat) {
+#' @examples
+#' string_to_format <- "call( 3)"
+#' pd <- styler:::compute_parse_data_nested(string_to_format)
+#' styler:::pre_visit(pd, c(default_style_guide_attributes))
+#' @export
+default_style_guide_attributes <- function(pd_flat) {
 
   init_pd <-
     initialize_newlines(pd_flat) %>%
@@ -17,6 +22,11 @@ initialize_attributes <- function(pd_flat) {
   init_pd
 }
 
+#' Initialize attributes
+#'
+#' @name initialize_attributes
+NULL
+
 #' @describeIn initialize_attributes Initializes `newlines` and `lag_newlines`.
 initialize_newlines <- function(pd_flat) {
   pd_flat$line3 <- lead(pd_flat$line1, default = tail(pd_flat$line2, 1))

R/nested_to_tree.R

@@ -7,7 +7,7 @@
 #' @importFrom purrr when
 create_tree <- function(text, structure_only = FALSE) {
   compute_parse_data_nested(text) %>%
-    pre_visit(c(initialize_attributes)) %>%
+    pre_visit(c(default_style_guide_attributes)) %>%
     create_node_from_nested_root(structure_only) %>%
     as.data.frame()
 }
@@ -25,7 +25,7 @@ create_tree <- function(text, structure_only = FALSE) {
 #' if (getRversion() >= 3.2) {
 #' code <- "a <- function(x) { if(x > 1) { 1+1 } else {x} }"
 #' nested_pd <- styler:::compute_parse_data_nested(code)
-#' initialized <- styler:::pre_visit(nested_pd, c(styler:::initialize_attributes))
+#' initialized <- styler:::pre_visit(nested_pd, c(default_style_guide_attributes))
 #' styler:::create_node_from_nested_root(initialized, structure_only = FALSE)
 #' }
 create_node_from_nested_root <- function(pd_nested, structure_only) {

R/serialized_tests.R

@@ -144,7 +144,7 @@ NULL
 style_empty <- function(text) {
   transformers <- list(
     # transformer functions
-    initialize = initialize_attributes,
+    initialize = default_style_guide_attributes,
     line_break = NULL,
     space      = NULL,
     token      = NULL,
@@ -163,7 +163,7 @@ style_op <- function(text) {
 
   transformers <- list(
     # transformer functions
-    initialize = initialize_attributes,
+    initialize = default_style_guide_attributes,
     line_break = NULL,
     space      = partial(indent_op, indent_by = 2),
     token      = NULL,

R/style_guides.R

@@ -24,7 +24,7 @@ NULL
 #'   line breaks to one if there is none and leave the code untouched otherwise.
 #'   See 'Examples'.
 #' @param start_comments_with_one_space Whether or not comments should start
-#'   with only one space (see [start_comments_with_space()]).
+#'   with only one space (see `start_comments_with_space()`).
 #' @inheritParams create_style_guide
 #' @param math_token_spacing A list of parameters that define spacing around
 #'   math token, conveniently constructed using [specify_math_token_spacing()].
@@ -46,6 +46,7 @@ NULL
 #' @family style_guides
 #' @examples
 #' style_text("call( 1)", style = tidyverse_style, scope = "spaces")
+#' style_text("call( 1)", transformers = tidyverse_style(strict = TRUE))
 #' style_text(c("ab <- 3", "a  <-3"), strict = FALSE) # keeps alignment of "<-"
 #' style_text(c("ab <- 3", "a  <-3"), strict = TRUE) # drops alignment of "<-"
 #' @importFrom purrr partial
@@ -135,7 +136,7 @@ tidyverse_style <- function(scope = "tokens",
 
   create_style_guide(
     # transformer functions
-    initialize        = initialize_attributes,
+    initialize        = default_style_guide_attributes,
     line_break        = line_break_manipulators,
     space             = space_manipulators,
     token             = token_manipulators,
@@ -153,8 +154,8 @@ tidyverse_style <- function(scope = "tokens",
 #' transformer function corresponds to one styling rule. The output of this
 #' function can be used as an argument for \code{style} in top level functions
 #' like [style_text()] and friends.
-#' @param initialize A function that initializes various variables on each
-#'   level of nesting.
+#' @param initialize The bare name of a function that initializes various
+#'   variables on each level of nesting.
 #' @param line_break A list of transformer functions that manipulate line_break
 #'   information.
 #' @param space A list of transformer functions that manipulate spacing
@@ -165,8 +166,18 @@ tidyverse_style <- function(scope = "tokens",
 #'   should be used.
 #' @param reindention A list of parameters for regex re-indention, most
 #'   conveniently constructed using [specify_reindention()].
+#' @examples
+#' set_line_break_before_curly_opening <- function(pd_flat) {
+#'   op <- pd_flat$token %in% "'{'"
+#'   pd_flat$lag_newlines[op] <- 1L
+#'   pd_flat
+#' }
+#' set_line_break_before_curly_opening_style <- function() {
+#'   create_style_guide(line_break = set_line_break_before_curly_opening)
+#' }
+#' style_text("a <- function(x) { x }", style = set_line_break_before_curly_opening_style)
 #' @export
-create_style_guide <- function(initialize = initialize_attributes,
+create_style_guide <- function(initialize = default_style_guide_attributes,
                                line_break = NULL,
                                space = NULL,
                                token = NULL,
@@ -205,6 +216,10 @@ NULL
 
 #' @describeIn reindention Allows to specify which tokens are reindented and
 #'   how.
+#' @examples
+#' style_text("a <- xyz", reindention = specify_reindention(
+#'   regex_pattern = "xyz", indention = 4, comments_only = FALSE)
+#' )
 #' @export
 specify_reindention <- function(regex_pattern = NULL,
                                 indention = 0,
@@ -218,6 +233,8 @@ specify_reindention <- function(regex_pattern = NULL,
 #' @describeIn reindention Simple forwarder to
 #' `specify_reindention` with reindention according to the tidyverse style
 #' guide.
+#' @examples
+#' style_text("a <- xyz", reindention = tidyverse_reindention())
 #' @export
 tidyverse_reindention <- function() {
   specify_reindention(
@@ -281,6 +298,12 @@ specify_math_token_spacing <-
 #' @describeIn math_token_spacing Simple forwarder to
 #' `specify_math_token_spacing` with spacing around math tokens according to the
 #' tidyverse style guide.
+#' @examples
+#' style_text(
+#'   "1+1   -3",
+#'   math_token_spacing = tidyverse_math_token_spacing(),
+#'   strict = TRUE
+#' )
 #' @export
 tidyverse_math_token_spacing <- function() {
   specify_math_token_spacing(one = c("'+'", "'-'", "'*'", "'/'", "'^'"))

R/ui.R

@@ -31,9 +31,12 @@ NULL
 #' @family stylers
 #' @examples
 #' \dontrun{
-#' # the following is identical but the former is more convenient:
+#'
 #' style_pkg(style = tidyverse_style, strict = TRUE)
-#' style_pkg(transformers = tidyverse_style(strict = TRUE))
+#' style_pkg(
+#'   scope = "line_breaks",
+#'   math_token_spacing = specify_math_token_spacing(zero = "'+'")
+#' )
 #' }
 #' @export
 style_pkg <- function(pkg = ".",
@@ -112,6 +115,10 @@ style_text <- function(text,
 #' @inheritSection transform_files Value
 #' @inheritSection style_pkg Warning
 #' @family stylers
+#' @examples
+#' \dontrun{
+#' style_dir(file_type = "r")
+#' }
 #' @export
 style_dir <- function(path = ".",
                       ...,