Standardise get_*, set_*, update_* and replace_* prefixes. (#5802)

* standardise layer getters

* standardise theme accessors

* Make `get_last_plot()`

* propagate changes throughout

* adjust docs

* add news bullet

* missed a few replacements

* propagate to recent PRs

Author: teunbrand

NAMESPACE

@@ -421,6 +421,11 @@ export(geom_vline)
 export(get_alt_text)
 export(get_element_tree)
 export(get_guide_data)
+export(get_last_plot)
+export(get_layer_data)
+export(get_layer_grob)
+export(get_panel_scales)
+export(get_theme)
 export(gg_dep)
 export(ggpar)
 export(ggplot)
@@ -504,6 +509,7 @@ export(rel)
 export(remove_missing)
 export(render_axes)
 export(render_strips)
+export(replace_theme)
 export(reset_theme_settings)
 export(resolution)
 export(scale_alpha)
@@ -639,6 +645,7 @@ export(scale_y_sqrt)
 export(scale_y_time)
 export(sec_axis)
 export(set_last_plot)
+export(set_theme)
 export(sf_transform_xy)
 export(should_stop)
 export(stage)
@@ -704,6 +711,7 @@ export(unit)
 export(update_geom_defaults)
 export(update_labels)
 export(update_stat_defaults)
+export(update_theme)
 export(vars)
 export(waiver)
 export(wrap_dims)

NEWS.md

@@ -1,5 +1,20 @@
 # ggplot2 (development version)
 
+* Special getter and setter functions have been renamed for consistency, allowing
+  for better tab-completion with `get_*`- and `set_*`-prefixes. The old names 
+  remain available for backward compatibility (@teunbrand, #5568).
+  
+  | New name             | Old name          |
+  | -------------------- | ----------------- |
+  | `get_theme()`        | `theme_get()`     |
+  | `set_theme()`        | `theme_set()`     |
+  | `replace_theme()`    | `theme_replace()` |
+  | `update_theme()`     | `theme_update()`  |
+  | `get_last_plot()`    | `last_plot()`     |
+  | `get_layer_data()`   | `layer_data()`    |
+  | `get_layer_grob()`   | `layer_grob()`    |
+  | `get_panel_scales()` | `layer_scales()`  |
+
 * Discrete scales now support `minor_breaks`. This may only make sense in
   discrete position scales, where it affects the placement of minor ticks
   and minor gridlines (#5434).

R/guides-.R

@@ -787,7 +787,7 @@ Guides <- ggproto(
 #' # Coord polar doesn't support proper guides, so we get a list
 #' polar <- p + coord_polar()
 #' get_guide_data(polar, "theta", panel = 2)
-get_guide_data <- function(plot = last_plot(), aesthetic, panel = 1L) {
+get_guide_data <- function(plot = get_last_plot(), aesthetic, panel = 1L) {
 
   check_string(aesthetic, allow_empty = FALSE)
   aesthetic <- standardise_aes_names(aesthetic)

R/plot-build.R

@@ -5,15 +5,15 @@
 #' a list of data frames (one for each layer), and a panel object, which
 #' contain all information about axis limits, breaks etc.
 #'
-#' `layer_data()`, `layer_grob()`, and `layer_scales()` are helper
+#' `get_layer_data()`, `get_layer_grob()`, and `get_panel_scales()` are helper
 #' functions that return the data, grob, or scales associated with a given
 #' layer. These are useful for tests.
 #'
 #' @param plot ggplot object
-#' @param i An integer. In `layer_data()`, the data to return (in the order added to the
-#'   plot). In `layer_grob()`, the grob to return (in the order added to the
-#'   plot). In `layer_scales()`, the row of a facet to return scales for.
-#' @param j An integer. In `layer_scales()`, the column of a facet to return
+#' @param i An integer. In `get_layer_data()`, the data to return (in the order added to the
+#'   plot). In `get_layer_grob()`, the grob to return (in the order added to the
+#'   plot). In `get_panel_scales()`, the row of a facet to return scales for.
+#' @param j An integer. In `get_panel_scales()`, the column of a facet to return
 #'   scales for.
 #' @seealso
 #' [print.ggplot()] and [benchplot()] for
@@ -125,13 +125,16 @@ ggplot_build.ggplot <- function(plot) {
 
 #' @export
 #' @rdname ggplot_build
-layer_data <- function(plot = last_plot(), i = 1L) {
+get_layer_data <- function(plot = get_last_plot(), i = 1L) {
   ggplot_build(plot)$data[[i]]
 }
+#' @export
+#' @rdname ggplot_build
+layer_data <- get_layer_data
 
 #' @export
 #' @rdname ggplot_build
-layer_scales <- function(plot = last_plot(), i = 1L, j = 1L) {
+get_panel_scales <- function(plot = get_last_plot(), i = 1L, j = 1L) {
   b <- ggplot_build(plot)
 
   layout <- b$layout$layout
@@ -145,12 +148,20 @@ layer_scales <- function(plot = last_plot(), i = 1L, j = 1L) {
 
 #' @export
 #' @rdname ggplot_build
-layer_grob <- function(plot = last_plot(), i = 1L) {
+layer_scales <- get_panel_scales
+
+#' @export
+#' @rdname ggplot_build
+get_layer_grob <- function(plot = get_last_plot(), i = 1L) {
   b <- ggplot_build(plot)
 
   b$plot$layers[[i]]$draw_geom(b$data[[i]], b$layout)
 }
 
+#' @export
+#' @rdname ggplot_build
+layer_grob <- get_layer_grob
+
 #' Build a plot with all the usual bits and pieces.
 #'
 #' This function builds all grobs necessary for displaying the plot, and

R/plot-last.R

@@ -21,4 +21,8 @@ set_last_plot <- function(value) .store$set(value)
 #' @seealso [ggsave()]
 #' @export
 #' @keywords internal
-last_plot <- function() .store$get()
+get_last_plot <- function() .store$get()
+
+#' @export
+#' @rdname get_last_plot
+last_plot <- get_last_plot

R/save.R

@@ -89,7 +89,7 @@
 #' dev.off()
 #'
 #' }
-ggsave <- function(filename, plot = last_plot(),
+ggsave <- function(filename, plot = get_last_plot(),
                    device = NULL, path = NULL, scale = 1,
                    width = NA, height = NA, units = c("in", "cm", "mm", "px"),
                    dpi = 300, limitsize = TRUE, bg = NULL,

R/theme-current.R

@@ -5,39 +5,39 @@ NULL
 #' Get, set, and modify the active theme
 #'
 #' The current/active theme (see [theme()]) is automatically applied to every
-#' plot you draw. Use `theme_get()` to get the current theme, and `theme_set()` to
-#' completely override it. `theme_update()` and `theme_replace()` are shorthands for
+#' plot you draw. Use `get_theme()` to get the current theme, and `set_theme()` to
+#' completely override it. `update_theme()` and `replace_theme()` are shorthands for
 #' changing individual elements.
 #'
 #' @section Adding on to a theme:
 #'
 #'   `+` and `%+replace%` can be used to modify elements in themes.
 #'
 #'   `+` updates the elements of e1 that differ from elements specified (not
-#'   NULL) in e2. Thus this operator can be used to incrementally add or modify
+#'   `NULL`) in e2. Thus this operator can be used to incrementally add or modify
 #'   attributes of a ggplot theme.
 #'
 #'   In contrast, `%+replace%` replaces the entire element; any element of a
 #'   theme not specified in e2 will not be present in the resulting theme (i.e.
-#'   NULL). Thus this operator can be used to overwrite an entire theme.
+#'   `NULL`). Thus this operator can be used to overwrite an entire theme.
 #'
-#'   `theme_update()` uses the `+` operator, so that any unspecified values in the
+#'   `update_theme()` uses the `+` operator, so that any unspecified values in the
 #'   theme element will default to the values they are set in the theme.
-#'   `theme_replace()` uses `%+replace%` to completely replace the element, so any
+#'   `replace_theme()` uses `%+replace%` to completely replace the element, so any
 #'   unspecified values will overwrite the current value in the theme with
 #'   `NULL`.
 #'
-#'   In summary, the main differences between `theme_set()`, `theme_update()`,
-#'   and `theme_replace()` are:
-#'   * `theme_set()` completely overrides the current theme.
-#'   * `theme_update()` modifies a particular element of the current theme
+#'   In summary, the main differences between `set_theme()`, `update_theme()`,
+#'   and `replace_theme()` are:
+#'   * `set_theme()` completely overrides the current theme.
+#'   * `update_theme()` modifies a particular element of the current theme
 #'   using the `+` operator.
-#'   * `theme_replace()` modifies a particular element of the current theme
+#'   * `replace_theme()` modifies a particular element of the current theme
 #'   using the `%+replace%` operator.
 #'
 #' @param ... named list of theme settings
 #' @param e1,e2 Theme and element to combine
-#' @return `theme_set()`, `theme_update()`, and `theme_replace()`
+#' @return `set_theme()`, `update_theme()`, and `replace_theme()`
 #'   invisibly return the previous theme so you can easily save it, then
 #'   later restore it.
 #' @seealso [+.gg()]
@@ -47,25 +47,25 @@ NULL
 #'   geom_point()
 #' p
 #'
-#' # Use theme_set() to completely override the current theme.
-#' # theme_update() and theme_replace() are similar except they
+#' # Use set_theme() to completely override the current theme.
+#' # update_theme() and replace_theme() are similar except they
 #' # apply directly to the current/active theme.
-#' # theme_update() modifies a particular element of the current theme.
+#' # update_theme() modifies a particular element of the current theme.
 #' # Here we have the old theme so we can later restore it.
 #' # Note that the theme is applied when the plot is drawn, not
 #' # when it is created.
-#' old <- theme_set(theme_bw())
+#' old <- set_theme(theme_bw())
 #' p
 #'
-#' theme_set(old)
-#' theme_update(panel.grid.minor = element_line(colour = "red"))
+#' set_theme(old)
+#' update_theme(panel.grid.minor = element_line(colour = "red"))
 #' p
 #'
-#' theme_set(old)
-#' theme_replace(panel.grid.minor = element_line(colour = "red"))
+#' set_theme(old)
+#' replace_theme(panel.grid.minor = element_line(colour = "red"))
 #' p
 #'
-#' theme_set(old)
+#' set_theme(old)
 #' p
 #'
 #'
@@ -82,33 +82,49 @@ NULL
 #'   theme(text = element_text(family = "Times"))
 #' rep_el$text
 #'
-theme_get <- function() {
+get_theme <- function() {
   ggplot_global$theme_current
 }
 
-#' @rdname theme_get
+#' @export
+#' @rdname get_theme
+theme_get <- get_theme
+
+#' @rdname get_theme
 #' @param new new theme (a list of theme elements)
 #' @export
-theme_set <- function(new) {
+set_theme <- function(new) {
   check_object(new, is.theme, "a {.cls theme} object")
   old <- ggplot_global$theme_current
   ggplot_global$theme_current <- new
   invisible(old)
 }
 
-#' @rdname theme_get
 #' @export
-theme_update <- function(...) {
-  theme_set(theme_get() + theme(...))
+#' @rdname get_theme
+theme_set <- set_theme
+
+#' @rdname get_theme
+#' @export
+update_theme <- function(...) {
+  set_theme(get_theme() + theme(...))
 }
 
-#' @rdname theme_get
 #' @export
-theme_replace <- function(...) {
-  theme_set(theme_get() %+replace% theme(...))
+#' @rdname get_theme
+theme_update <- update_theme
+
+#' @rdname get_theme
+#' @export
+replace_theme <- function(...) {
+  set_theme(get_theme() %+replace% theme(...))
 }
 
-#' @rdname theme_get
+#' @export
+#' @rdname get_theme
+theme_replace <- replace_theme
+
+#' @rdname get_theme
 #' @export
 "%+replace%" <- function(e1, e2) {
   if (!is.theme(e1) || !is.theme(e2)) {

R/theme.R

@@ -561,7 +561,7 @@ validate_theme <- function(theme, tree = get_element_tree(), call = caller_env()
 }
 
 # Combine plot defaults with current theme to get complete theme for a plot
-plot_theme <- function(x, default = theme_get()) {
+plot_theme <- function(x, default = get_theme()) {
   theme <- x$theme
 
   # apply theme defaults appropriately if needed