Rename methods_register() to S7_on_load() (#688)

Keeping `methods_register()` around for backward compatibility.

Fixes #615

Author: hadley

NAMESPACE

@@ -44,6 +44,7 @@ export(S7_dispatch)
 export(S7_inherits)
 export(S7_object)
 export(S7_on_build)
+export(S7_on_load)
 export(as_class)
 export(check_is_S7)
 export(class_Date)

NEWS.md

@@ -35,6 +35,7 @@
 * `S7_data<-()` now preserves attributes (like `names` or `dim`) from the replacement data instead of carrying over the originals, so resizing the underlying data works correctly (#478).
 * `S7_error_method_not_found` now has a correct class vector without a duplicate `"error"` entry (@jjjermiah, #604).
 * `S7_inherits()` and `check_is_S7()` now accept any class specification (S7 class, S7 union, S3 class, S4 class, or base type wrapper like `class_integer`), not just S7 classes (#556).
+* `S7_on_load()` is the new name for `methods_register()`, giving it a nicer symmetry with `S7_on_build()`; `methods_register()` remains available for backward compatibility (#615).
 * `str()` on S7 objects that inherit from data.frame (or other S3 classes whose underlying data has a `dim` attribute incompatible with the bare base type) no longer errors (#494).
 * `super()` now works with S3 and S4 objects, not just S7 objects (#500).
 * `validate()` now signals validation errors with class `S7_error_validation_failed`, so they can be caught with `tryCatch()` (#602, #605).

R/external-generic.R

@@ -10,7 +10,7 @@
 #' dependency, and sometimes you want a soft dependency, only registering the
 #' method if the package is already installed. `new_external_generic()` allows
 #' you to provide the minimal needed information about a generic so that methods
-#' can be registered at run time, as needed, using [methods_register()].
+#' can be registered at run time, as needed, using [S7_on_load()].
 #'
 #' Note that in tests, you'll need to explicitly call the generic from the
 #' external package with `pkg::generic()`.

R/hooks.R

@@ -3,7 +3,7 @@
 #' @description
 #' When using S7 in a package, add two hooks to your `zzz.R`:
 #'
-#' * Call `methods_register()` from `.onLoad()`. This is S7's way of
+#' * Call `S7_on_load()` from `.onLoad()`. This is S7's way of
 #'   registering methods, rather than using `NAMESPACE` directives like S3 and
 #'   S4 do. It ensures that methods for generics (S3, S4, and S7) defined in
 #'   other packages are registered as needed when your package is loaded. This
@@ -15,21 +15,34 @@
 #'   after all method registration is complete. This avoids embedding copies
 #'   of external generics in your package when you use `method<-`.
 #'
+#' `S7_on_load()` was previously known as `methods_register()`. This function is
+#' retained for backward compatibility but new code should use `S7_on_load()`.
+#'
 #' See `vignette("packages")` for more details.
 #'
 #' @importFrom utils getFromNamespace packageName
 #' @returns Nothing; both functions are called for their side-effects.
 #' @examples
 #' # In zzz.R:
 #' .onLoad <- function(...) {
-#'   S7::methods_register()
+#'   S7::S7_on_load()
 #' }
 #' S7::S7_on_build()
 #' @export
+S7_on_load <- function() {
+  S7_on_load_(parent.frame())
+}
+
+#' @export
+#' @rdname S7_on_load
 methods_register <- function() {
-  package <- packageName(parent.frame())
-  ns <- topenv(parent.frame())
-  # TODO?: check/enforce that methods_register() is being called from .onLoad()
+  S7_on_load_(parent.frame())
+}
+
+S7_on_load_ <- function(env) {
+  package <- packageName(env)
+  ns <- topenv(env)
+  # TODO?: check/enforce that S7_on_load() is being called from .onLoad()
 
   tbl <- S7_methods_table(package)
 
@@ -46,7 +59,7 @@ methods_register <- function() {
 }
 
 #' @export
-#' @rdname methods_register
+#' @rdname S7_on_load
 S7_on_build <- function() {
   strip_generic_sentinels(topenv(parent.frame()))
 }

R/method-register.R

@@ -12,7 +12,7 @@
 #' But this is not a general method registration function: at least one of
 #' `generic` and `signature` needs to be from S7.
 #'
-#' Note that if you are writing a package, you must call [methods_register()]
+#' Note that if you are writing a package, you must call [S7_on_load()]
 #' in your `.onLoad`. This ensures that all methods are dynamically registered
 #' when needed.
 #'

_pkgdown.yml

@@ -40,7 +40,7 @@ reference:
     Functions needed when using S7 within a package. See `vignette("packages")`
     for more details.
   contents:
-  - methods_register
+  - S7_on_load
   - new_external_generic
 
 - title: Compatibility

man/methods_register.Rd man/S7_on_load.Rdman/methods_register.Rd renamed to man/S7_on_load.Rd

@@ -35,5 +35,5 @@ S7::method(another_s3_generic, an_s7_class) <- function(x) "foo"
 
 
 .onLoad <- function(libname, pkgname) {
-  S7::methods_register()
+  S7::S7_on_load()
 }