Skip to content

Commit d6fef86

Browse files
krlmlrkrlmlr
authored
Merge pull request #921 from tidyverse/f-912-options
- New `?tibble_options` help page (#912).
2 parents 096f0c6 + fc618e1 commit d6fef86

11 files changed

+262
-204
lines changed

‎R/aaa-options.R

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
make_option_impl <- function(getter, option_name = NULL, env = caller_env()) {
2+
getter_body <- enexpr(getter)
3+
4+
if (is.null(option_name)) {
5+
# Assuming that the call is getOption()
6+
option_name <- getter_body[[2]]
7+
stopifnot(is.character(option_name))
8+
}
9+
name <- sub(paste0(utils::packageName(env), "."), "", option_name, fixed = TRUE)
10+
getter_name <- paste0("get_", utils::packageName(env), "_option_", name)
11+
local_setter_name <- paste0("local_", utils::packageName(env), "_option_", name)
12+
setter_name <- paste0("set_", utils::packageName(env), "_option_", name)
13+
14+
local_setter_body <- expr(
15+
{
16+
out <- !!call2("local_options", !!option_name := sym("value"), .frame = sym("env"))
17+
!!call2(getter_name)
18+
invisible(out[[1]])
19+
}
20+
)
21+
22+
setter_body <- expr(
23+
{
24+
out <- !!call2("options", !!option_name := sym("value"))
25+
!!call2(getter_name)
26+
invisible(out[[1]])
27+
}
28+
)
29+
30+
body <- expr({
31+
if (missing(!!sym("value"))) {
32+
if (!missing(local)) {
33+
abort("Can't pass `local` argument if `value` is missing.")
34+
}
35+
!!getter_body
36+
} else if (local) !!local_setter_body
37+
else !!setter_body
38+
})
39+
40+
args <- pairlist2(value = , local = FALSE, env = quote(caller_env()))
41+
42+
assign(getter_name, new_function(list(), getter_body, env = env), env)
43+
assign(local_setter_name, new_function(args[c(1, 3)], local_setter_body, env = env), env)
44+
assign(setter_name, new_function(args[1], setter_body, env = env), env)
45+
46+
new_function(args, body, env = env)
47+
}

‎R/options-tibble.R

+51
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
## Legacy, for trunc_mat() and friends
2+
op.tibble <- list(
3+
tibble.print_min = 10L,
4+
tibble.print_max = 20L,
5+
tibble.width = NULL,
6+
tibble.max_extra_cols = 100L
7+
)
8+
9+
tibble_opt <- function(x, dplyr = TRUE) {
10+
x_tibble <- paste0("tibble.", x)
11+
res <- getOption(x_tibble)
12+
if (!is.null(res)) {
13+
return(res)
14+
}
15+
16+
if (dplyr) {
17+
x_dplyr <- paste0("dplyr.", x)
18+
res <- getOption(x_dplyr)
19+
if (!is.null(res)) {
20+
return(res)
21+
}
22+
}
23+
24+
op.tibble[[x_tibble]]
25+
}
26+
27+
tibble_width <- function(width) {
28+
if (!is.null(width)) {
29+
return(width)
30+
}
31+
32+
width <- tibble_opt("width")
33+
if (!is.null(width)) {
34+
return(width)
35+
}
36+
37+
getOption("width")
38+
}
39+
40+
tibble_glimpse_width <- function(width) {
41+
if (!is.null(width)) {
42+
return(width)
43+
}
44+
45+
width <- tibble_opt("width")
46+
if (!is.null(width) && is.finite(width)) {
47+
return(width)
48+
}
49+
50+
getOption("width")
51+
}

‎R/options.R

+38-52
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,39 @@
1-
## user-facing docs kept in `formatting` topic; see utils-format.R
2-
## Exception: tibble.view_max, in `tibble-package`
3-
op.tibble <- list(
4-
tibble.print_max = 20L,
5-
tibble.print_min = 10L,
6-
tibble.width = NULL,
7-
tibble.max_extra_cols = 100L,
8-
tibble.view_max = 1000L
1+
#' Package options
2+
#'
3+
#' Options that affect interactive display.
4+
#' See [pillar_options] for options that affect display on the console.
5+
#'
6+
#' These options can be set via [options()] and queried via [getOption()].
7+
#' For this, add a `tibble.` prefix (the package name and a dot) to the option name.
8+
#' Example: for an option `foo`, use `options(tibble.foo = value)` to set it
9+
#' and `getOption("tibble.foo")` to retrieve the current value.
10+
#' An option value of `NULL` means that the default is used.
11+
#'
12+
#' @format NULL
13+
#'
14+
#' @examples
15+
#' # Default setting:
16+
#' getOption("tibble.view_max")
17+
#'
18+
#' # Change for the duration of the session:
19+
#' old <- options(tibble.view_max = 100)
20+
#'
21+
#' # view() would show only 100 rows e.g. for a lazy data frame
22+
#'
23+
#' # Change back to the original value:
24+
#' options(old)
25+
#'
26+
#' # Local scope:
27+
#' local({
28+
#' rlang::local_options(tibble.view_max = 100)
29+
#' # view() would show only 100 rows e.g. for a lazy data frame
30+
#' })
31+
#' # view() would show the default 1000 rows e.g. for a lazy data frame
32+
#' @section Options for the tibble package:
33+
tibble_options <- list2(
34+
#' - `view_max`: Maximum number of rows shown by [view()]
35+
#' if the input is not a data frame, passed on to [head()]. Default: `1000`.
36+
view_max = make_option_impl(
37+
getOption("tibble.view_max", default = tibble_opt("view_max", 1000L))
38+
),
939
)
10-
11-
tibble_opt <- function(x, dplyr = TRUE) {
12-
x_tibble <- paste0("tibble.", x)
13-
res <- getOption(x_tibble)
14-
if (!is.null(res)) {
15-
return(res)
16-
}
17-
18-
if (dplyr) {
19-
x_dplyr <- paste0("dplyr.", x)
20-
res <- getOption(x_dplyr)
21-
if (!is.null(res)) {
22-
return(res)
23-
}
24-
}
25-
26-
op.tibble[[x_tibble]]
27-
}
28-
29-
tibble_width <- function(width) {
30-
if (!is.null(width)) {
31-
return(width)
32-
}
33-
34-
width <- tibble_opt("width")
35-
if (!is.null(width)) {
36-
return(width)
37-
}
38-
39-
getOption("width")
40-
}
41-
42-
tibble_glimpse_width <- function(width) {
43-
if (!is.null(width)) {
44-
return(width)
45-
}
46-
47-
width <- tibble_opt("width")
48-
if (!is.null(width) && is.finite(width)) {
49-
return(width)
50-
}
51-
52-
getOption("width")
53-
}

‎R/print.R

+35-32
Original file line numberDiff line numberDiff line change
@@ -7,47 +7,37 @@
77
#' supplemented by a summary of the remaining rows and columns.
88
#' * Tibble reveals the type of each column, which keeps the user informed about
99
#' whether a variable is, e.g., `<chr>` or `<fct>` (character versus factor).
10+
#' See `vignette("types", package = "pillar")` for an overview of common
11+
#' type abbreviations.
1012
#'
1113
#' Printing can be tweaked for a one-off call by calling `print()` explicitly
1214
#' and setting arguments like `n` and `width`. More persistent control is
13-
#' available by setting the options described below.
15+
#' available by setting the options described in [pillar_options].
1416
#' See also `vignette("digits", package = "pillar")` for a comparison to base options,
1517
#' and [num()] and [char()] for creating columns with custom formatting options.
1618
#'
1719
#' As of tibble 3.1.0, printing is handled entirely by the \pkg{pillar} package.
18-
#' If you implement a package that extend tibble,
20+
#' If you implement a package that extends tibble,
1921
#' the printed output can be customized in various ways.
20-
#' See `vignette("extending", package = "pillar")` for details.
21-
#'
22-
#' @inherit pillar::pillar_options
23-
#' @section Package options:
24-
#'
25-
#' The following options control printing of `tbl` and `tbl_df` objects:
26-
#'
27-
#' * `tibble.print_max`: Row number threshold: Maximum number of rows printed.
28-
#' Set to `Inf` to always print all rows. Default: 20.
29-
#' * `tibble.print_min`: Number of rows printed if row number threshold is
30-
#' exceeded. Default: 10.
31-
#' * `tibble.width`: Output width. Default: `NULL` (use `width` option).
32-
#' * `tibble.max_extra_cols`: Number of extra columns printed in reduced form.
33-
#' Default: 100.
34-
#'
35-
#' The output uses color and highlighting according to the `"cli.num_colors"` option.
36-
#' Set it to `1` to suppress colored and highlighted output.
22+
#' See `vignette("extending", package = "pillar")` for details,
23+
#' and [pillar_options] for options that control the display in the console.
3724
#'
25+
# Copied from pillar::format.tbl() to avoid roxygen2 warning
3826
#' @param x Object to format or print.
39-
#' @param ... Other arguments passed on to individual methods.
27+
#' @param ... Passed on to [tbl_format_setup()].
4028
#' @param n Number of rows to show. If `NULL`, the default, will print all rows
41-
#' if less than option `tibble.print_max`. Otherwise, will print
42-
#' `tibble.print_min` rows.
29+
#' if less than the `print_max` [option][pillar_options].
30+
#' Otherwise, will print as many rows as specified by the
31+
#' `print_min` [option][pillar_options].
4332
#' @param width Width of text output to generate. This defaults to `NULL`, which
44-
#' means use `getOption("tibble.width")` or (if also `NULL`)
45-
#' `getOption("width")`; the latter displays only the columns that fit on one
46-
#' screen. You can also set `options(tibble.width = Inf)` to override this
47-
#' default and always print all columns, this may be slow for very wide tibbles.
48-
#' @param n_extra Number of extra columns to print abbreviated information for,
49-
#' if the width is too small for the entire tibble. If `NULL`, the default,
50-
#' will print information about at most `tibble.max_extra_cols` extra columns.
33+
#' means use the `width` [option][pillar_options].
34+
#' @param max_extra_cols Number of extra columns to print abbreviated information for,
35+
#' if the width is too small for the entire tibble. If `NULL`,
36+
#' the `max_extra_cols` [option][pillar_options] is used.
37+
#' The previously defined `n_extra` argument is soft-deprecated.
38+
#' @param max_footer_lines Maximum number of footer lines. If `NULL`,
39+
#' the `max_footer_lines` [option][pillar_options] is used.
40+
#'
5141
#' @examples
5242
#' print(as_tibble(mtcars))
5343
#' print(as_tibble(mtcars), n = 1)
@@ -70,13 +60,15 @@ NULL
7060

7161
# Only for documentation, doesn't do anything
7262
#' @rdname formatting
73-
print.tbl_df <- function(x, ..., n = NULL, width = NULL, n_extra = NULL) {
63+
print.tbl_df <- function(x, width = NULL, ..., n = NULL, max_extra_cols = NULL,
64+
max_footer_lines = NULL) {
7465
NextMethod()
7566
}
7667

7768
# Only for documentation, doesn't do anything
7869
#' @rdname formatting
79-
format.tbl_df <- function(x, ..., n = NULL, width = NULL, n_extra = NULL) {
70+
format.tbl_df <- function(x, width = NULL, ..., n = NULL, max_extra_cols = NULL,
71+
max_footer_lines = NULL) {
8072
NextMethod()
8173
}
8274

@@ -90,7 +82,18 @@ format.tbl_df <- function(x, ..., n = NULL, width = NULL, n_extra = NULL) {
9082
#' the printed output can be customized in various ways.
9183
#' See `vignette("extending", package = "pillar")` for details.
9284
#'
93-
#' @inheritParams formatting
85+
#' @param x Object to format or print.
86+
#' @param n Number of rows to show. If `NULL`, the default, will print all rows
87+
#' if less than option `tibble.print_max`. Otherwise, will print
88+
#' `tibble.print_min` rows.
89+
#' @param width Width of text output to generate. This defaults to `NULL`, which
90+
#' means use `getOption("tibble.width")` or (if also `NULL`)
91+
#' `getOption("width")`; the latter displays only the columns that fit on one
92+
#' screen. You can also set `options(tibble.width = Inf)` to override this
93+
#' default and always print all columns, this may be slow for very wide tibbles.
94+
#' @param n_extra Number of extra columns to print abbreviated information for,
95+
#' if the width is too small for the entire tibble. If `NULL`, the default,
96+
#' will print information about at most `tibble.max_extra_cols` extra columns.
9497
#' @export
9598
#' @keywords internal
9699
trunc_mat <- function(x, n = NULL, width = NULL, n_extra = NULL) {

‎R/tibble-package.R

+1-4
Original file line numberDiff line numberDiff line change
@@ -36,8 +36,5 @@
3636
#' * Create a tibble: [tibble()], [as_tibble()], [tribble()], [enframe()]
3737
#' * Inspect a tibble: [print.tbl()], [glimpse()]
3838
#' * Details on the S3 `tbl_df` class: [`tbl_df-class`]
39-
#' @section Package options:
40-
#' The following option is used for viewing tabular data with `view()`:
41-
#' - `tibble.view_max`: Maximum number of rows shown if the input is not a
42-
#' data frame. Default: 1000.
39+
#' * Package options: [tibble_options]
4340
"_PACKAGE"

‎R/view.R

+3-3
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
#' the deparsed expression is used.
1919
#' @param ... Unused, must be empty.
2020
#' @param n Maximum number of rows to display. Only used if `x` is not a
21-
#' data frame.
21+
#' data frame. Uses the `view_max` [option][tibble_options] by default.
2222
#'
2323
#' @export
2424
view <- function(x, title = NULL, ..., n = NULL) {
@@ -32,12 +32,12 @@ view <- function(x, title = NULL, ..., n = NULL) {
3232

3333
if (!is.data.frame(x)) {
3434
if (is.null(n)) {
35-
n <- tibble_opt("view_max")
35+
n <- get_tibble_option_view_max()
3636
}
3737
x <- head(x, n + 1)
3838
x <- as.data.frame(x)
3939
if (nrow(x) > n) {
40-
message("Showing first ", n, " rows.")
40+
message("Showing the first ", n, " rows.")
4141
x <- head(x, n)
4242
}
4343
}

0 commit comments

Comments
 (0)