Export, document, and use := (#658)

`foo := bar()` is a shorthand for `foo <- bar(name = "foo")`, thus it's a convenient syntax for use this `new_class()` and `new_generic()`.  We now use it in all tests and public facing documentation, while reserving the right to change the implementation in the future.

Fixes #466

Author: hadley

NAMESPACE

@@ -32,6 +32,7 @@ S3method(str,S7_object)
 S3method(str,S7_property)
 S3method(str,S7_super)
 S3method(str,S7_union)
+export(":=")
 export("S7_data<-")
 export("method<-")
 export("prop<-")

NEWS.md

@@ -1,5 +1,6 @@
 # S7 (development version)
 
+* New `:=` operator creates and names an object in one step, so `Foo := new_class()` is equivalent to `Foo <- new_class(name = "Foo")` (#658).
 * Errors thrown by S7 now report the function where they occurred, making it easier to track down the source of a problem (#646).
 * `class_POSIXct` uses the `tzone` attribute (not `tz`), and allows it to be absent (#401).
 * Base type wrappers like `class_integer` now define their constructor and validator in the S7 namespace. (#553).

R/S3.R

@@ -84,7 +84,7 @@
 #' # No checking, just used for dispatch
 #' Date <- new_S3_class("Date")
 #'
-#' my_generic <- new_generic("my_generic", "x")
+#' my_generic := new_generic("x")
 #' method(my_generic, Date) <- function(x) "This is a date"
 #'
 #' my_generic(Sys.Date())

R/S4.R

@@ -14,7 +14,7 @@
 #'   standardGeneric("S4_generic")
 #' })
 #'
-#' Foo <- new_class("Foo")
+#' Foo := new_class()
 #' S4_register(Foo)
 #' method(S4_generic, Foo) <- function(x) "Hello"
 #'

R/base-environment.R

@@ -20,7 +20,7 @@
 #'
 #' @export
 #' @examples
-#' Counter <- new_class("Counter", class_environment)
+#' Counter := new_class(class_environment)
 #' counter <- Counter()
 #' counter$n <- 0L
 #'

R/bind.R

@@ -0,0 +1,45 @@
+#' Create and name an object in one step
+#'
+#' @description
+#' Functions like [new_class()] and [new_generic()] take a `name` that, by
+#' convention, matches the name of the variable that you assign their result
+#' to. The `:=` operator eliminates this duplication: `Foo := new_class()` is
+#' equivalent to `Foo <- new_class(name = "Foo")`.
+#'
+#' `:=` works with any function that has a `name` argument, but bear in mind
+#' that it adds `name` to the call as a named argument, so any other arguments
+#' supplied positionally will shift to fill the remaining parameters.
+#'
+#' @usage lhs := rhs
+#' @param lhs A bare symbol: both the name of the variable to create and the
+#'   `name` supplied to the right-hand side.
+#' @param rhs A call to a function with a `name` argument.
+#' @return The result of evaluating `rhs`, which is also assigned to `lhs` in
+#'   the calling environment, returned invisibly.
+#' @export
+#' @rdname named-bind
+#' @examples
+#' Range := new_class(properties = list(
+#'   start = class_double,
+#'   end = class_double
+#' ))
+#' Range
+#'
+#' describe := new_generic("x")
+#' describe
+`:=` <- function(lhs, rhs) {
+  cl <- sys.call()
+  if (!is.symbol(cl[[2L]])) {
+    stop2("Left-hand side of `:=` must be a symbol.")
+  }
+  if (!is.call(cl[[3L]])) {
+    stop2("Right-hand side of `:=` must be a function call.")
+  }
+  if ("name" %in% names(cl[[3L]])) {
+    stop2("Right-hand side of `:=` must not already supply a `name` argument.")
+  }
+
+  cl[[1L]] <- quote(`<-`)
+  cl[[3L]]$name <- as.character(cl[[2L]])
+  invisible(eval.parent(cl))
+}

R/class.R

@@ -11,8 +11,9 @@
 #'   CamelCase for S7 class names, but it is not required.)
 #'
 #'   The result of calling `new_class()` should always be assigned to a variable
-#'   with this name, i.e. `Foo <- new_class("Foo")`. This object both represents
-#'   the class and is used to construct new instances of the class.
+#'   with this name, i.e. `Foo <- new_class("Foo", ...)` or
+#'   `Foo := new_class(...)`. This object both represents the class and is used
+#'   to construct new instances of the class.
 #' @param parent The parent class to inherit behavior from.
 #'   There are three options:
 #'
@@ -59,7 +60,7 @@
 #' @export
 #' @examples
 #' # Create an class that represents a range using a numeric start and end
-#' Range <- new_class("Range",
+#' Range := new_class(
 #'   properties = list(
 #'     start = class_numeric,
 #'     end = class_numeric
@@ -77,7 +78,7 @@
 #'
 #' # But we might also want to use a validator to ensure that start and end
 #' # are length 1, and that start is < end
-#' Range <- new_class("Range",
+#' Range := new_class(
 #'   properties = list(
 #'     start = class_numeric,
 #'     end = class_numeric
@@ -397,7 +398,7 @@ str.S7_object <- function(object, ..., nest.lev = 0) {
 #' @returns A class specification.
 #' @export
 #' @examples
-#' Foo <- new_class("Foo")
+#' Foo := new_class()
 #' S7_class(Foo())
 #'
 #' # Also works on non-S7 objects

R/convert.R

@@ -54,8 +54,8 @@
 #'   is not possible.
 #' @export
 #' @examples
-#' Foo1 <- new_class("Foo1", properties = list(x = class_integer))
-#' Foo2 <- new_class("Foo2", Foo1, properties = list(y = class_double))
+#' Foo1 := new_class(properties = list(x = class_integer))
+#' Foo2 := new_class(Foo1, properties = list(y = class_double))
 #'
 #' # Upcasting: S7 provides a default implementation for coercing an object
 #' # to one of its parent classes:
@@ -94,9 +94,9 @@
 #' # Conversely, `convert()` *does* use inheritance for `from`, so a method
 #' # registered on a parent class is also used for its children. This holds
 #' # even when upcasting, where it overrides the default property stripping:
-#' Bar1 <- new_class("Bar1", properties = list(label = class_character))
-#' Bar2 <- new_class("Bar2", Bar1)
-#' Bar3 <- new_class("Bar3", Bar2)
+#' Bar1 := new_class(properties = list(label = class_character))
+#' Bar2 := new_class(Bar1)
+#' Bar3 := new_class(Bar2)
 #' method(convert, list(Bar2, Bar1)) <- function(from, to, ...) {
 #'   Bar1(label = "from a Bar2 or one of its children")
 #' }
@@ -106,7 +106,7 @@
 #' # This `from`-inheritance is limited to classes more specific than `to`. A
 #' # method whose `from` is a *parent* of `to` would downcast, so it is skipped.
 #' # For example, this method downcasts a Foo1 to a Foo2:
-#' Foo3 <- new_class("Foo3", Foo2, properties = list(z = class_double))
+#' Foo3 := new_class(Foo2, properties = list(z = class_double))
 #' method(convert, list(Foo1, Foo2)) <- function(from, to, ...) Foo2(y = -1)
 #'
 #' # Upcasting a Foo3 to a Foo2 ignores that inherited downcasting method,

R/data.R

@@ -13,7 +13,7 @@
 #'   invisibly.
 #' @export
 #' @examples
-#' Text <- new_class("Text", parent = class_character)
+#' Text := new_class(parent = class_character)
 #' y <- Text(c(foo = "bar"))
 #' y
 #' S7_data(y)
@@ -22,7 +22,7 @@
 #' y
 #'
 #' # S3 classes are preserved
-#' MyDF <- new_class("MyDF", parent = class_data.frame)
+#' MyDF := new_class(parent = class_data.frame)
 #' S7_data(MyDF(data.frame(x = 1, y = 2)))
 S7_data <- function(object) {
   check_is_S7(object)

R/external-generic.R

@@ -24,7 +24,7 @@
 #'   `S7_external_generic`.
 #' @export
 #' @examples
-#' MyClass <- new_class("MyClass")
+#' MyClass := new_class()
 #'
 #' your_generic <- new_external_generic("stats", "median", "x")
 #' method(your_generic, MyClass) <- function(x) "Hi!"