|
| 1 | +#' Set ggplot2 edition |
| 2 | +#' |
| 3 | +#' ggplot2 uses the 'edition' concept to manage the lifecycles of functions and |
| 4 | +#' arguments. Setting a recent edition opens up the latest features but also |
| 5 | +#' closes down deprecated and superseded functionality. |
| 6 | +#' |
| 7 | +#' @param edition An edition. Possible values currently include `"2026"` only. |
| 8 | +#' Can be `NULL` (default) to unset an edition. |
| 9 | +#' |
| 10 | +#' @returns For `set_ggplot2_edition()`, the previous `edition` value and for |
| 11 | +#' `local_ggplot2_edition()`: `NULL`. Thesef unction are called for the side |
| 12 | +#' effect of setting the edition though. For `with_ggplot2_edition`, the |
| 13 | +#' result of the evaluation. For `get_ggplot2_edition()`, the currently |
| 14 | +#' active edition. |
| 15 | +#' |
| 16 | +#' @export |
| 17 | +#' @keywords internal |
| 18 | +#' |
| 19 | +#' @examples |
| 20 | +#' # Setting an edition |
| 21 | +#' set_ggplot2_edition(2026) |
| 22 | +#' |
| 23 | +#' # Getting the edition |
| 24 | +#' get_ggplot2_edition() |
| 25 | +#' |
| 26 | +#' |
| 27 | +#' # Unsetting an edition |
| 28 | +#' set_ggplot2_edition() |
| 29 | +#' |
| 30 | +#' # Using withr-like scoping |
| 31 | +#' with_ggplot2_edition(2026, get_ggplot2_edition()) |
| 32 | +set_ggplot2_edition <- function(edition = NULL) { |
| 33 | + old <- ggplot_global$edition |
| 34 | + ggplot_global$edition <- validate_edition(edition) |
| 35 | + invisible(old) |
| 36 | +} |
| 37 | + |
| 38 | +#' @export |
| 39 | +#' @param env An `environment` to use for scoping. |
| 40 | +#' @rdname set_ggplot2_edition |
| 41 | +local_ggplot2_edition <- function(edition = NULL, env = parent.frame()) { |
| 42 | + old <- set_ggplot2_edition(edition) |
| 43 | + withr::defer(set_ggplot2_edition(old), envir = env) |
| 44 | +} |
| 45 | + |
| 46 | +#' @export |
| 47 | +#' @param code Code to execute in the temporary environment. |
| 48 | +#' @rdname set_ggplot2_edition |
| 49 | +with_ggplot2_edition <- function(edition = NULL, code) { |
| 50 | + local_ggplot2_edition(edition) |
| 51 | + code |
| 52 | +} |
| 53 | + |
| 54 | +#' @export |
| 55 | +#' @rdname set_ggplot2_edition |
| 56 | +get_ggplot2_edition <- function() { |
| 57 | + ggplot_global$edition[[1]] |
| 58 | +} |
| 59 | + |
| 60 | +# Any new editions should be appended here and anchored to a version |
| 61 | +edition_versions <- c( |
| 62 | + "2025" = "4.0.0", |
| 63 | + "2026" = "4.1.0" |
| 64 | +) |
| 65 | + |
| 66 | +validate_edition <- function(edition, allow_null = TRUE, call = caller_env()) { |
| 67 | + if (is.null(edition) && allow_null) { |
| 68 | + return(NULL) |
| 69 | + } |
| 70 | + edition <- as.character(edition) |
| 71 | + check_string(edition, allow_empty = FALSE, call = call) |
| 72 | + arg_match0(edition, names(edition_versions), error_call = call) |
| 73 | +} |
| 74 | + |
| 75 | +edition_require <- function(edition = NULL, what, call = caller_env()) { |
| 76 | + edition <- validate_edition(edition) |
| 77 | + current_edition <- get_ggplot2_edition() |
| 78 | + if ( |
| 79 | + !is.null(current_edition) && |
| 80 | + as.numeric(current_edition) >= as.numeric(edition) |
| 81 | + ) { |
| 82 | + return(invisible()) |
| 83 | + } |
| 84 | + cli::cli_abort( |
| 85 | + "{what} requires the {edition} edition of {.pkg ggplot2}.", |
| 86 | + call = call |
| 87 | + ) |
| 88 | +} |
| 89 | + |
| 90 | +deprecate <- function(when, ..., id = NULL, always = FALSE, user_env = NULL, |
| 91 | + escalate = NULL) { |
| 92 | + |
| 93 | + defunct <- "3.0.0" |
| 94 | + full <- "3.4.0" |
| 95 | + soft <- utils::packageVersion("ggplot2") |
| 96 | + |
| 97 | + if (identical(escalate, "delay")) { |
| 98 | + soft <- full |
| 99 | + full <- defunct |
| 100 | + defunct <- "0.0.0" |
| 101 | + } |
| 102 | + |
| 103 | + edition <- get_ggplot2_edition() |
| 104 | + if (!is.null(edition) && edition %in% names(edition_versions)) { |
| 105 | + soft <- full <- defunct <- edition_versions[[edition]] |
| 106 | + } |
| 107 | + |
| 108 | + version <- as.package_version(when) |
| 109 | + if (version < defunct || identical(escalate, "abort")) { |
| 110 | + lifecycle::deprecate_stop(when, ...) |
| 111 | + } |
| 112 | + user_env <- user_env %||% getOption("ggplot2_plot_env") %||% caller_env(2) |
| 113 | + if (version <= full || identical(escalate, "warn")) { |
| 114 | + lifecycle::deprecate_warn(when, ..., id = id, always = always, user_env = user_env) |
| 115 | + } else if (version <= soft) { |
| 116 | + lifecycle::deprecate_soft(when, ..., id = id, user_env = user_env) |
| 117 | + } |
| 118 | + invisible() |
| 119 | +} |
| 120 | + |
| 121 | +supersede <- function(edition, what, with = NULL, ..., env = caller_env()) { |
| 122 | + current_edition <- get_ggplot2_edition() |
| 123 | + if ( |
| 124 | + !is.null(current_edition) && |
| 125 | + current_edition %in% names(edition_versions) && |
| 126 | + as.numeric(current_edition) >= as.numeric(edition) |
| 127 | + ) { |
| 128 | + lifecycle::deprecate_stop( |
| 129 | + when = paste0("edition ", edition), |
| 130 | + what = what, |
| 131 | + with = with, |
| 132 | + env = env |
| 133 | + ) |
| 134 | + } |
| 135 | + lifecycle::signal_stage( |
| 136 | + stage = "superseded", |
| 137 | + what = what, |
| 138 | + with = with, |
| 139 | + env = env |
| 140 | + ) |
| 141 | +} |
0 commit comments