From 355e16263941bf99026801a8921b8a24019f53eb Mon Sep 17 00:00:00 2001 From: Tomasz Kalinowski Date: Wed, 16 Oct 2024 10:50:49 -0400 Subject: [PATCH 1/8] initial draft blog post --- .Rbuildignore | 1 + S7.Rproj | 1 + vignettes/release-announcement-0-2-0.Rmd | 137 +++++++++++++++++++++++ 3 files changed, 139 insertions(+) create mode 100644 vignettes/release-announcement-0-2-0.Rmd diff --git a/.Rbuildignore b/.Rbuildignore index f9d9a651..2c1727ed 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -18,3 +18,4 @@ ^compile_commands\.json$ ^\.cache$ ^\.vscode$ +^vignettes/release-announcement-0-2-0\.Rmd$ diff --git a/S7.Rproj b/S7.Rproj index ef6fa310..f0f0c454 100644 --- a/S7.Rproj +++ b/S7.Rproj @@ -20,3 +20,4 @@ BuildType: Package PackageUseDevtools: Yes PackageInstallArgs: --no-multiarch --with-keep.source PackageRoxygenize: rd,collate,namespace +MarkdownWrap: Sentence diff --git a/vignettes/release-announcement-0-2-0.Rmd b/vignettes/release-announcement-0-2-0.Rmd new file mode 100644 index 00000000..f072d744 --- /dev/null +++ b/vignettes/release-announcement-0-2-0.Rmd @@ -0,0 +1,137 @@ +```{r} +#| include: false +knitr::opts_chunk$set(collapse = TRUE, comment = "#>") +``` + +We're excited to announce that the second release of the S7 package is now available on CRAN! +S7 is a new object-oriented programming (OOP) system designed to succeed both S3 and S4. +You might wonder why R needs a new OOP system when we already have two. +The reason lies in the history of R's OOP journey: S3 is a simple and effective system for single dispatch, while S4 adds formal class definitions and multiple dispatch, but at the cost of complexity. +This has forced developers to choose between the simplicity of S3 and the sophistication of S4. + +The goal of S7 is to unify the OOP landscape by building on S3’s existing dispatch system and incorporating the most useful features of S4 (along with some new ones), all with a simpler syntax. + +S7’s design and implementation have been a collaborative effort by a working group from the [R Consortium](https://www.r-consortium.org), including representatives from R-Core, Bioconductor, tidyverse/Posit, ROpenSci, and the wider R community. +Since S7 builds on S3, it is fully compatible with existing S3-based code. +It's also been thoughtfully designed to work with S4, and as we learn more about the challenges of transitioning from S4 to S7, we’ll continue to add features to ease this process. + +Our long-term goal is to include S7 in base R, but for now, you can install it from CRAN: + +```{r, eval = FALSE} +install.packages("S7") +``` + +## What’s New in the Second Release + +The second release of S7 brings refinements and bug fixes. +Key new features include: + +- The ability to define classes with lazy property default values. +- Initialization logic for properties with custom setters. +- Substantial speed improvements for property setting and getting with `@` and `@<-`. +- Expanded support for base S3 classes. +- `convert()` now has a default method for transforming a parent class instance into a subclass. + +Additionally, there are numerous bug fixes and quality-of-life improvements, such as better error messages, improved support for base Ops methods, and compatibility improvements for using `@` in R versions prior to 4.3. + +## Usage + +Let’s dive into the basics of S7. +To learn more, check out the package vignettes, including a more detailed introduction in [`vignette("S7")`](https://rconsortium.github.io/OOP-WG/articles/S7.html), and coverage of generics and methods in [`vignette("generics-methods")`](https://rconsortium.github.io/OOP-WG/articles/generics-methods.html), and classes and objects in [`vignette("classes-objects")`](https://rconsortium.github.io/OOP-WG/articles/classes-objects.html). + +```{r} +library(S7) +``` + +### Classes and Objects + +S7 classes have formal definitions, specified by `new_class()`, which includes a list of properties and an optional validator. +For example, the following code creates a `range` class with `start` and `end` properties, and a validator to ensure that `start` is always less than `end`: + +```{r} +range <- new_class("range", + properties = list( + start = class_double, + end = class_double + ), + validator = function(self) { + if (length(self@start) != 1) { + "@start must be length 1" + } else if (length(self@end) != 1) { + "@end must be length 1" + } else if (self@end < self@start) { + "@end must be greater than or equal to @start" + } + } +) +``` + +`new_class()` returns the class object, which also serves as the constructor to create instances of the class: + +```{r} +x <- range(start = 1, end = 10) +x +``` + +### Properties + +The data an object holds are called its **properties**. +Use `@` to get and set properties: + +```{r} +x@start +x@end <- 20 +x +``` + +Properties are automatically validated against the type declared in `new_class()` (in this case, `double`) and checked by the class **validator**: + +```{r, error = TRUE} +x@end <- "x" # Error: must be a double +x@end <- -1 # Error: must be >= start +``` + +### Generics and Methods + +Like S3 and S4, S7 uses **functional OOP**, where methods belong to **generic** functions, and method calls look like regular function calls: `generic(object, arg2, arg3)`. +A generic uses the types of its arguments to automatically pick the appropriate method implementation. + +You can create a new generic with `new_generic()`, specifying the arguments to dispatch on: + +```{r} +inside <- new_generic("inside", "x") +``` + +To define a method for a specific class, use `method(generic, class) <- implementation`: + +```{r} +method(inside, range) <- function(x, y) { + y >= x@start & y <= x@end +} + +inside(x, c(0, 5, 10, 15)) +``` + +Printing the generic shows its methods: + +```{r} +inside +``` + +And you can retrieve the method for a specific class: + +```{r} +method(inside, range) +``` + +## Known Limitations + +While we are pleased with S7’s design, there are still some limitations: + +- S7 objects can be serialized to disk (with `saveRDS()`), but the current implementation saves the entire class specification with each object. This may change in the future. +- Support for implicit S3 classes `"array"` and `"matrix"` is still in development. + +We expect the community will uncover more issues as S7 is more widely adopted. +If you encounter any problems, please file an issue at . +We appreciate your feedback in helping us make S7 even better! +😃 From b0ee189e70262bb70c143e5f59d1d06b9c8d2707 Mon Sep 17 00:00:00 2001 From: Tomasz Kalinowski Date: Wed, 16 Oct 2024 13:52:37 -0400 Subject: [PATCH 2/8] Update vignettes/release-announcement-0-2-0.Rmd Co-authored-by: Hadley Wickham --- vignettes/release-announcement-0-2-0.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vignettes/release-announcement-0-2-0.Rmd b/vignettes/release-announcement-0-2-0.Rmd index f072d744..f53b63c9 100644 --- a/vignettes/release-announcement-0-2-0.Rmd +++ b/vignettes/release-announcement-0-2-0.Rmd @@ -3,7 +3,7 @@ knitr::opts_chunk$set(collapse = TRUE, comment = "#>") ``` -We're excited to announce that the second release of the S7 package is now available on CRAN! +We're excited to announce that the S7 0.2.0 is now available on CRAN! S7 is a new object-oriented programming (OOP) system designed to succeed both S3 and S4. You might wonder why R needs a new OOP system when we already have two. The reason lies in the history of R's OOP journey: S3 is a simple and effective system for single dispatch, while S4 adds formal class definitions and multiple dispatch, but at the cost of complexity. From f1f861d8e8e4dc0fbea121dcfed0ddfe3729e6ae Mon Sep 17 00:00:00 2001 From: Tomasz Kalinowski Date: Wed, 16 Oct 2024 13:52:43 -0400 Subject: [PATCH 3/8] Update vignettes/release-announcement-0-2-0.Rmd Co-authored-by: Hadley Wickham --- vignettes/release-announcement-0-2-0.Rmd | 1 - 1 file changed, 1 deletion(-) diff --git a/vignettes/release-announcement-0-2-0.Rmd b/vignettes/release-announcement-0-2-0.Rmd index f53b63c9..f2b79f03 100644 --- a/vignettes/release-announcement-0-2-0.Rmd +++ b/vignettes/release-announcement-0-2-0.Rmd @@ -10,7 +10,6 @@ The reason lies in the history of R's OOP journey: S3 is a simple and effective This has forced developers to choose between the simplicity of S3 and the sophistication of S4. The goal of S7 is to unify the OOP landscape by building on S3’s existing dispatch system and incorporating the most useful features of S4 (along with some new ones), all with a simpler syntax. - S7’s design and implementation have been a collaborative effort by a working group from the [R Consortium](https://www.r-consortium.org), including representatives from R-Core, Bioconductor, tidyverse/Posit, ROpenSci, and the wider R community. Since S7 builds on S3, it is fully compatible with existing S3-based code. It's also been thoughtfully designed to work with S4, and as we learn more about the challenges of transitioning from S4 to S7, we’ll continue to add features to ease this process. From 83ca42c06423798a439334975f24a8188835b458 Mon Sep 17 00:00:00 2001 From: Tomasz Kalinowski Date: Wed, 16 Oct 2024 13:52:51 -0400 Subject: [PATCH 4/8] Update vignettes/release-announcement-0-2-0.Rmd Co-authored-by: Hadley Wickham --- vignettes/release-announcement-0-2-0.Rmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vignettes/release-announcement-0-2-0.Rmd b/vignettes/release-announcement-0-2-0.Rmd index f2b79f03..20ce78c0 100644 --- a/vignettes/release-announcement-0-2-0.Rmd +++ b/vignettes/release-announcement-0-2-0.Rmd @@ -20,7 +20,7 @@ Our long-term goal is to include S7 in base R, but for now, you can install it f install.packages("S7") ``` -## What’s New in the Second Release +## What’s new in the second release The second release of S7 brings refinements and bug fixes. Key new features include: From 2ce84f8f7ea8fdb441a775b09467b00605167c96 Mon Sep 17 00:00:00 2001 From: Tomasz Kalinowski Date: Wed, 16 Oct 2024 13:53:04 -0400 Subject: [PATCH 5/8] Update vignettes/release-announcement-0-2-0.Rmd Co-authored-by: Hadley Wickham --- vignettes/release-announcement-0-2-0.Rmd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/vignettes/release-announcement-0-2-0.Rmd b/vignettes/release-announcement-0-2-0.Rmd index 20ce78c0..327e8120 100644 --- a/vignettes/release-announcement-0-2-0.Rmd +++ b/vignettes/release-announcement-0-2-0.Rmd @@ -86,8 +86,8 @@ x Properties are automatically validated against the type declared in `new_class()` (in this case, `double`) and checked by the class **validator**: ```{r, error = TRUE} -x@end <- "x" # Error: must be a double -x@end <- -1 # Error: must be >= start +x@end <- "x" +x@end <- -1 ``` ### Generics and Methods From f31bb5d8434a2527ec3848f8c38f15fa8b8e7f54 Mon Sep 17 00:00:00 2001 From: Tomasz Kalinowski Date: Wed, 16 Oct 2024 14:43:47 -0400 Subject: [PATCH 6/8] move `library(S7)` earlier --- vignettes/release-announcement-0-2-0.Rmd | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/vignettes/release-announcement-0-2-0.Rmd b/vignettes/release-announcement-0-2-0.Rmd index 327e8120..d5190b35 100644 --- a/vignettes/release-announcement-0-2-0.Rmd +++ b/vignettes/release-announcement-0-2-0.Rmd @@ -35,13 +35,14 @@ Additionally, there are numerous bug fixes and quality-of-life improvements, suc ## Usage -Let’s dive into the basics of S7. -To learn more, check out the package vignettes, including a more detailed introduction in [`vignette("S7")`](https://rconsortium.github.io/OOP-WG/articles/S7.html), and coverage of generics and methods in [`vignette("generics-methods")`](https://rconsortium.github.io/OOP-WG/articles/generics-methods.html), and classes and objects in [`vignette("classes-objects")`](https://rconsortium.github.io/OOP-WG/articles/classes-objects.html). - ```{r} library(S7) ``` +Let's dive into the basics of S7. +To learn more, check out the package vignettes, including a more detailed introduction in [`vignette("S7")`](https://rconsortium.github.io/OOP-WG/articles/S7.html), and coverage of generics and methods in [`vignette("generics-methods")`](https://rconsortium.github.io/OOP-WG/articles/generics-methods.html), and classes and objects in [`vignette("classes-objects")`](https://rconsortium.github.io/OOP-WG/articles/classes-objects.html). + + ### Classes and Objects S7 classes have formal definitions, specified by `new_class()`, which includes a list of properties and an optional validator. From 5167eccfaafdbcfdbca407a67e227d2c21271454 Mon Sep 17 00:00:00 2001 From: Tomasz Kalinowski Date: Wed, 16 Oct 2024 14:44:14 -0400 Subject: [PATCH 7/8] remove gremlins --- vignettes/release-announcement-0-2-0.Rmd | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/vignettes/release-announcement-0-2-0.Rmd b/vignettes/release-announcement-0-2-0.Rmd index d5190b35..ecee1336 100644 --- a/vignettes/release-announcement-0-2-0.Rmd +++ b/vignettes/release-announcement-0-2-0.Rmd @@ -9,10 +9,10 @@ You might wonder why R needs a new OOP system when we already have two. The reason lies in the history of R's OOP journey: S3 is a simple and effective system for single dispatch, while S4 adds formal class definitions and multiple dispatch, but at the cost of complexity. This has forced developers to choose between the simplicity of S3 and the sophistication of S4. -The goal of S7 is to unify the OOP landscape by building on S3’s existing dispatch system and incorporating the most useful features of S4 (along with some new ones), all with a simpler syntax. -S7’s design and implementation have been a collaborative effort by a working group from the [R Consortium](https://www.r-consortium.org), including representatives from R-Core, Bioconductor, tidyverse/Posit, ROpenSci, and the wider R community. +The goal of S7 is to unify the OOP landscape by building on S3's existing dispatch system and incorporating the most useful features of S4 (along with some new ones), all with a simpler syntax. +S7's design and implementation have been a collaborative effort by a working group from the [R Consortium](https://www.r-consortium.org), including representatives from R-Core, Bioconductor, tidyverse/Posit, ROpenSci, and the wider R community. Since S7 builds on S3, it is fully compatible with existing S3-based code. -It's also been thoughtfully designed to work with S4, and as we learn more about the challenges of transitioning from S4 to S7, we’ll continue to add features to ease this process. +It's also been thoughtfully designed to work with S4, and as we learn more about the challenges of transitioning from S4 to S7, we'll continue to add features to ease this process. Our long-term goal is to include S7 in base R, but for now, you can install it from CRAN: @@ -20,7 +20,7 @@ Our long-term goal is to include S7 in base R, but for now, you can install it f install.packages("S7") ``` -## What’s new in the second release +## What's new in the second release The second release of S7 brings refinements and bug fixes. Key new features include: @@ -88,7 +88,7 @@ Properties are automatically validated against the type declared in `new_class() ```{r, error = TRUE} x@end <- "x" -x@end <- -1 +x@end <- -1 ``` ### Generics and Methods @@ -126,7 +126,7 @@ method(inside, range) ## Known Limitations -While we are pleased with S7’s design, there are still some limitations: +While we are pleased with S7's design, there are still some limitations: - S7 objects can be serialized to disk (with `saveRDS()`), but the current implementation saves the entire class specification with each object. This may change in the future. - Support for implicit S3 classes `"array"` and `"matrix"` is still in development. From 647faa26ce51b94507f417cf7c0b0b0b0d394058 Mon Sep 17 00:00:00 2001 From: Tomasz Kalinowski Date: Wed, 16 Oct 2024 15:01:56 -0400 Subject: [PATCH 8/8] Add "Who should use S7" section --- vignettes/release-announcement-0-2-0.Rmd | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/vignettes/release-announcement-0-2-0.Rmd b/vignettes/release-announcement-0-2-0.Rmd index ecee1336..b57ffaf1 100644 --- a/vignettes/release-announcement-0-2-0.Rmd +++ b/vignettes/release-announcement-0-2-0.Rmd @@ -33,6 +33,10 @@ Key new features include: Additionally, there are numerous bug fixes and quality-of-life improvements, such as better error messages, improved support for base Ops methods, and compatibility improvements for using `@` in R versions prior to 4.3. +## Who should use S7 + +S7 is a great fit for R users who like to try new things but don't need to be the first. It's already used in several CRAN packages, and the tidyverse team is applying it in new projects. While you may still run into a few issues, many early problems have been resolved. + ## Usage ```{r}