Reimplement classes in S7 (#6364)

* add S7 as import

* custom properties for theme elements

* convert theme elements to S7 classes

* adapt element definitions

* convert element_grob to S7 generic

* replace merge_element by S7

* implement `$.element` for backward compatibility

* Use S7 properties

* fix `inherits()` issues

* fix misc issues

* Revert "implement `$.element` for backward compatibility"

This reverts commit b038e8f.

* don't rely on `element$prop`

* move element properties

* convert `margin` to S7

* I liked index properties as an idea but apparently they print badly

* adapt failing example

* import S7

* convert theme to S7

* Reimplement S3 <uneval> into S7 <mapping>

* convert labels to S7

* make S7 class_ggplot

* Use `@` as accessor

* double dispatch for `ggplot_add()`

* Write methods for external generics as S7

* backward compatibility for ggplot class

* Implement <ggplot_built> as S7

* implement `as.gtable` methods

* rename mapping to class_mapping

* refine class_ggplot_built and related functions

* also access ggplot_built slots with normal extractors

* resolve gnarlyness in S3/S7 method conflicts

* fix esoteric 'promise already under evaluation' error

* fix series of minor issues

* export theme as class

* export labels class

* collect classes in one place

* revert @include decisions

* Make S7 generic of `get_alt_text()`

* backport `@`

* exempt classes from pkgdown

* lol at my incompetence

* allow variant error messages

* workaround for old R versions

* update pkgdown index

* backport `@`

* S7-aware `is_theme_element()`

* utility for grabbing props

* use classic extractors and subassignment

* fallback for `register_theme_elements()`

* contingencies for `inherits(x, <S7>)` on old R versions

* use `is_theme()`

* sprinkle notes

* bump staged deprecations

* add linejoins

* Disable `ggtext::element_markdown()` example

* fix failing tests

* redocument

* fix doc links

* soft-deprecate `%+%`

* simplify logic block

* don't evaluate code temporarily in FAQ example

* run revdepcheck

* recover from S3 mappings

* enable classic subsetting for ggplot_built

* fix typo

* prevent NSE shenannigans

* avoid `%+%` in test code

* add 'meta' property to track arbitrary fields

* document new property

* fix stretchy guide bug

* backward compatibility for `ggplot_add()`

* backward compatibility for `ggplot_add()`

* notes for the future

* backward compatibility for `ggplot_gtable()`

* backwards compatibility for `element_grob()`

* keep theme class

* add news bullet

* redirect other news

* add `italic`/`fontweight`/`fontwidth` properties (#6458)

* contingencies for old elements

* left out null/blank handling to from methods to generic

* also merge s3 elements

* revdepcheck

* remove outdated duplicate

* append old element classes

* append old uneval class

* append old ggplot classes

* allow for numeric `face`

* Symmetry between `$` and `[[` methods

* Revert `ggplot()` constructor to S3

* fallback for unit margins

* repair invalid theme

* make `rotate_just()` resilient for mixed S3/S7 classes

* redocument/snapshot

* revdepcheck

* contend with vector input

* unify mapping validation

* more carefullyl extract margins

* try to prevent cyclical `+`

* include snapshots

* protection against vectorised input

* fix  typo

* add `as.list()` method

* be fussy about margin input length

* tiny version bump

* allow numeric colour

* defend against insanity

---------

Co-authored-by: Thomas Lin Pedersen <thomasp85@gmail.com>

Author: teunbrand

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: ggplot2
 Title: Create Elegant Data Visualisations Using the Grammar of Graphics
-Version: 3.5.2.9000
+Version: 3.5.2.9001
 Authors@R: c(
     person("Hadley", "Wickham", , "hadley@posit.co", role = "aut",
            comment = c(ORCID = "0000-0003-4757-117X")),
@@ -40,6 +40,7 @@ Imports:
     isoband,
     lifecycle (> 1.0.1),
     rlang (>= 1.1.0),
+    S7,
     scales (>= 1.4.0),
     stats,
     vctrs (>= 0.6.0),
@@ -95,6 +96,7 @@ Collate:
     'compat-plyr.R'
     'utilities.R'
     'aes.R'
+    'all-classes.R'
     'annotation-borders.R'
     'utilities-checks.R'
     'legend-draw.R'
@@ -181,6 +183,8 @@ Collate:
     'grob-dotstack.R'
     'grob-null.R'
     'grouping.R'
+    'properties.R'
+    'margins.R'
     'theme-elements.R'
     'guide-.R'
     'guide-axis.R'
@@ -204,7 +208,6 @@ Collate:
     'layer-sf.R'
     'layout.R'
     'limits.R'
-    'margins.R'
     'performance.R'
     'plot-build.R'
     'plot-construction.R'

NAMESPACE

@@ -1,31 +1,35 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method("$","ggplot2::element")
+S3method("$","ggplot2::gg")
+S3method("$","ggplot2::theme")
 S3method("$",ggproto)
 S3method("$",ggproto_parent)
-S3method("$",theme)
-S3method("$<-",uneval)
-S3method("+",gg)
+S3method("$<-","ggplot2::element")
+S3method("$<-","ggplot2::gg")
+S3method("$<-","ggplot2::mapping")
+S3method("[","ggplot2::element")
+S3method("[","ggplot2::gg")
+S3method("[","ggplot2::mapping")
 S3method("[",mapped_discrete)
-S3method("[",uneval)
+S3method("[<-","ggplot2::element")
+S3method("[<-","ggplot2::gg")
+S3method("[<-","ggplot2::mapping")
 S3method("[<-",mapped_discrete)
-S3method("[<-",uneval)
+S3method("[[","ggplot2::element")
+S3method("[[","ggplot2::gg")
 S3method("[[",ggproto)
-S3method("[[<-",uneval)
+S3method("[[<-","ggplot2::element")
+S3method("[[<-","ggplot2::gg")
+S3method("[[<-","ggplot2::mapping")
 S3method(.DollarNames,ggproto)
 S3method(as.data.frame,mapped_discrete)
-S3method(as.gtable,ggplot)
-S3method(as.gtable,ggplot_built)
 S3method(as.list,ggproto)
 S3method(autolayer,default)
 S3method(autoplot,default)
 S3method(c,mapped_discrete)
 S3method(drawDetails,zeroGrob)
-S3method(element_grob,element_blank)
-S3method(element_grob,element_line)
-S3method(element_grob,element_point)
-S3method(element_grob,element_polygon)
-S3method(element_grob,element_rect)
-S3method(element_grob,element_text)
+S3method(element_grob,default)
 S3method(format,ggproto)
 S3method(format,ggproto_method)
 S3method(format,rd_section_aesthetics)
@@ -52,30 +56,12 @@ S3method(fortify,sfg)
 S3method(fortify,summary.glht)
 S3method(fortify,tbl)
 S3method(fortify,tbl_df)
-S3method(get_alt_text,ggplot)
-S3method(get_alt_text,ggplot_built)
-S3method(get_alt_text,gtable)
 S3method(ggplot,"function")
 S3method(ggplot,default)
-S3method(ggplot_add,"NULL")
-S3method(ggplot_add,"function")
-S3method(ggplot_add,Coord)
-S3method(ggplot_add,Facet)
-S3method(ggplot_add,Guides)
-S3method(ggplot_add,Layer)
-S3method(ggplot_add,Scale)
-S3method(ggplot_add,by)
-S3method(ggplot_add,data.frame)
 S3method(ggplot_add,default)
-S3method(ggplot_add,labels)
-S3method(ggplot_add,list)
-S3method(ggplot_add,theme)
-S3method(ggplot_add,uneval)
-S3method(ggplot_build,ggplot)
-S3method(ggplot_build,ggplot_built)
-S3method(ggplot_gtable,ggplot_built)
+S3method(ggplot_build,default)
+S3method(ggplot_gtable,default)
 S3method(grid.draw,absoluteGrob)
-S3method(grid.draw,ggplot)
 S3method(grobHeight,absoluteGrob)
 S3method(grobHeight,zeroGrob)
 S3method(grobWidth,absoluteGrob)
@@ -98,27 +84,22 @@ S3method(limits,numeric)
 S3method(makeContext,dotstackGrob)
 S3method(make_constructor,Geom)
 S3method(make_constructor,Stat)
-S3method(merge_element,default)
-S3method(merge_element,element)
-S3method(merge_element,element_blank)
-S3method(merge_element,margin)
 S3method(pattern_alpha,GridPattern)
 S3method(pattern_alpha,GridTilingPattern)
 S3method(pattern_alpha,default)
 S3method(pattern_alpha,list)
-S3method(plot,ggplot)
 S3method(predictdf,default)
 S3method(predictdf,glm)
 S3method(predictdf,locfit)
 S3method(predictdf,loess)
+S3method(print,"ggplot2::ggplot")
+S3method(print,"ggplot2::mapping")
+S3method(print,"ggplot2::theme")
 S3method(print,element)
-S3method(print,ggplot)
 S3method(print,ggplot2_bins)
 S3method(print,ggproto)
 S3method(print,ggproto_method)
 S3method(print,rel)
-S3method(print,theme)
-S3method(print,uneval)
 S3method(scale_type,Date)
 S3method(scale_type,POSIXt)
 S3method(scale_type,character)
@@ -132,7 +113,6 @@ S3method(scale_type,logical)
 S3method(scale_type,numeric)
 S3method(scale_type,ordered)
 S3method(scale_type,sfc)
-S3method(summary,ggplot)
 S3method(vec_cast,character.mapped_discrete)
 S3method(vec_cast,double.mapped_discrete)
 S3method(vec_cast,factor.mapped_discrete)
@@ -288,6 +268,7 @@ export(StatSummaryBin)
 export(StatSummaryHex)
 export(StatUnique)
 export(StatYdensity)
+export(add_gg)
 export(aes)
 export(aes_)
 export(aes_all)
@@ -311,8 +292,14 @@ export(autoplot)
 export(benchplot)
 export(binned_scale)
 export(borders)
+export(build_ggplot)
 export(calc_element)
 export(check_device)
+export(class_ggplot)
+export(class_ggplot_built)
+export(class_labels)
+export(class_mapping)
+export(class_theme)
 export(combine_vars)
 export(complete_theme)
 export(continuous_scale)
@@ -334,6 +321,7 @@ export(cut_width)
 export(datetime_scale)
 export(derive)
 export(discrete_scale)
+export(draw_element)
 export(draw_key_abline)
 export(draw_key_blank)
 export(draw_key_boxplot)
@@ -353,6 +341,7 @@ export(draw_key_vline)
 export(draw_key_vpath)
 export(dup_axis)
 export(el_def)
+export(element)
 export(element_blank)
 export(element_geom)
 export(element_grob)
@@ -456,6 +445,7 @@ export(ggproto)
 export(ggproto_parent)
 export(ggsave)
 export(ggtitle)
+export(gtable_ggplot)
 export(guide_axis)
 export(guide_axis_logticks)
 export(guide_axis_stack)
@@ -762,6 +752,7 @@ export(transform_position)
 export(translate_shape_string)
 export(unit)
 export(update_geom_defaults)
+export(update_ggplot)
 export(update_labels)
 export(update_stat_defaults)
 export(update_theme)
@@ -773,11 +764,13 @@ export(xlim)
 export(ylab)
 export(ylim)
 export(zeroGrob)
+if (getRversion() < "4.3.0") importFrom("S7", "@")
 import(grid)
 import(gtable)
 import(rlang)
 import(scales)
 import(vctrs)
+importFrom(S7,convert)
 importFrom(grid,arrow)
 importFrom(grid,unit)
 importFrom(lifecycle,deprecated)

NEWS.md

@@ -4,6 +4,7 @@
 
 ### Breaking changes
 
+* The S3 parts of ggplot2 have been replaced with S7 bits (#6352).
 * (breaking) `geom_violin(quantiles)` now has actual quantiles based on
   the data, rather than inferred quantiles based on the computed density. The
   `quantiles` parameter that replaces `draw_quantiles` now belongs to
@@ -20,9 +21,10 @@
     * Moved mgcv from Imports to Suggests
     * Moved tibble from Imports to Suggests
     * Removed glue dependency
-* Default labels are derived in `ggplot_build()` rather than
-  in `ggplot_add.Layer()`. This may affect code that accessed the `plot$labels` 
-  field (@teunbrand, #5894).
+* Default labels are derived in `build_ggplot()` (previously `ggplot_build()`) 
+  rather than in the layer method of `update_ggplot()` 
+  (previously `ggplot_add.Layer()`). This may affect code that accessed the 
+  `plot$labels` property (@teunbrand, #5894).
 
 ### Lifecycle changes
 

R/aes.R

@@ -46,8 +46,8 @@ NULL
 #' 'AsIs' variables.
 #'
 #' @family aesthetics documentation
-#' @return A list with class `uneval`. Components of the list are either
-#'   quosures or constants.
+#' @return An S7 object representing a list with class `mapping`. Components of
+#'   the list are either quosures or constants.
 #' @export
 #' @examples
 #' aes(x = mpg, y = wt)
@@ -105,13 +105,12 @@ aes <- function(x, y, ...) {
     inject(aes(!!!args))
   })
 
-  aes <- new_aes(args, env = parent.frame())
-  rename_aes(aes)
+  class_mapping(rename_aes(args), env = parent.frame())
 }
 
 #' @export
 #' @rdname is_tests
-is_mapping <- function(x) inherits(x, "uneval")
+is_mapping <- function(x) S7::S7_inherits(x, class_mapping)
 
 # Wrap symbolic objects in quosures but pull out constants out of
 # quosures for backward-compatibility
@@ -130,14 +129,10 @@ new_aesthetic <- function(x, env = globalenv()) {
 
   x
 }
-new_aes <- function(x, env = globalenv()) {
-  check_object(x, is.list, "a {.cls list}")
-  x <- lapply(x, new_aesthetic, env = env)
-  structure(x, class = "uneval")
-}
 
 #' @export
-print.uneval <- function(x, ...) {
+# TODO: should convert to proper S7 method once bug in S7 is resolved
+`print.ggplot2::mapping` <- function(x, ...) {
   cat("Aesthetic mapping: \n")
 
   if (length(x) == 0) {
@@ -152,26 +147,24 @@ print.uneval <- function(x, ...) {
   invisible(x)
 }
 
+# TODO: should convert to proper S7 method once bug in S7 is resolved
 #' @export
-"[.uneval" <- function(x, i, ...) {
-  new_aes(NextMethod())
+"[.ggplot2::mapping" <- function(x, i, ...) {
+  class_mapping(NextMethod())
 }
 
 # If necessary coerce replacements to quosures for compatibility
 #' @export
-"[[<-.uneval" <- function(x, i, value) {
-  new_aes(NextMethod())
+"[[<-.ggplot2::mapping" <- function(x, i, value) {
+  class_mapping(NextMethod())
 }
 #' @export
-"$<-.uneval" <- function(x, i, value) {
-  # Can't use NextMethod() because of a bug in R 3.1
-  x <- unclass(x)
-  x[[i]] <- value
-  new_aes(x)
+"$<-.ggplot2::mapping" <- function(x, i, value) {
+  class_mapping(NextMethod())
 }
 #' @export
-"[<-.uneval" <- function(x, i, value) {
-  new_aes(NextMethod())
+"[<-.ggplot2::mapping" <- function(x, i, value) {
+  class_mapping(NextMethod())
 }
 
 #' Standardise aesthetic names
@@ -212,8 +205,7 @@ substitute_aes <- function(x, fun = standardise_aes_symbols, ...) {
   x <- lapply(x, function(aesthetic) {
     as_quosure(fun(quo_get_expr(aesthetic), ...), env = environment(aesthetic))
   })
-  class(x) <- "uneval"
-  x
+  class_mapping(x)
 }
 # x is a quoted expression from inside aes()
 standardise_aes_symbols <- function(x) {
@@ -311,7 +303,7 @@ aes_ <- function(x, y, ...) {
     }
   }
   mapping <- lapply(mapping, as_quosure_aes)
-  structure(rename_aes(mapping), class = "uneval")
+  class_mapping(rename_aes(mapping))
 }
 
 #' @rdname aes_
@@ -337,7 +329,7 @@ aes_string <- function(x, y, ...) {
     new_aesthetic(x, env = caller_env)
   })
 
-  structure(rename_aes(mapping), class = "uneval")
+  class_mapping(rename_aes(mapping))
 }
 
 #' @export
@@ -358,10 +350,9 @@ aes_all <- function(vars) {
 
   # Quosure the symbols in the empty environment because they can only
   # refer to the data mask
-  structure(
-    lapply(vars, function(x) new_quosure(as.name(x), emptyenv())),
-    class = c("unlabelled_uneval", "uneval")
-  )
+  x <- class_mapping(lapply(vars, function(x) new_quosure(as.name(x), emptyenv())))
+  class(x) <- union("unlabelled", class(x))
+  x
 }
 
 #' Automatic aesthetic mapping