[R-pkg-devel] Three-argument S3method declaration does not seem to affect dispatching from inside the package.

So, calling the same generic function with the same class results
in different dispatching behaviour depending on whether the call is
from within the package doing the export or from the outside.

It does not depend on whether you export gen.formula() or not. When
you call gen() inside your package, the S3 dispatch mechanism finds a
method gen.formula defined in that environment (the package's
namespace), so it is called.

Note that disabling name-based dispatch implies two things: 1) the
inability to override your method by defining gen.formula in the
global environment, and 2) another package can break yours (i.e.,
internal calls to gen()) by registering an S3 method for gen() after
you.

Note that disabling name-based dispatch implies two things: 1) the
inability to override your method by defining gen.formula in the
global environment, and 2) another package can break yours (i.e.,
internal calls to gen()) by registering an S3 method for gen() after
you.

That's a good point.

   > library(anRpackage)
   > gen(a~b)

   I am the S3method-declared method.

   > gen.formula <- function(object, ...){message("I am the externally declared method.")}
   > gen(a~b)

   I am the externally declared method.

   > test_me()

   I am the tester. Which one will I call?
   I am the function with an unfortunate name.

In that case, I think that the least surprising behaviour would
prioritise declarations and methods "nearer" to the caller over those
"farther" from the caller (where "caller" is the caller of the generic,
not the generic itself), and, within that, give precedence to S3method
declarations over function names.

That is, for a call from inside a package, the order of precedence
would be as follows:
   1. S3method() in that package's NAMESPACE.
   2. Appropriately named function in that package (exported or not).
   3. Appropriately named function in calling environment (which may be
      GlobalEnv).
   4. S3method() in other loaded packages' NAMESPACEs.
   5. Appropriately named functions exported by other loaded packages'
      NAMESPACEs.

For a call from outside a package, the precedence is the same, but 1
and 2 are not relevant.

As far as I can tell, this is the current behaviour except for the
relative ordering of 1 and 2.

The thing is that, in R, "nearer" means "the calling environment"
(and then, other things). When you call test_me(), the calling
environment for gen() is the package namespace. When you call gen()
directly, thenthe calling environment is the global environment. So
what happens here follows the principle of least astonishment.

The issue here is that you are registering a non-standard name
(.gen.formula) for that generic and then defining what would be the
standard name (gen.formula) for... what purpose? IMHO, this is a bad
practice and should be avoided.

That is, for a call from inside a package, the order of precedence
would be as follows:
   1. S3method() in that package's NAMESPACE.
   2. Appropriately named function in that package (exported or
not).
   3. Appropriately named function in calling environment (which
may be
      GlobalEnv).
   4. S3method() in other loaded packages' NAMESPACEs.
   5. Appropriately named functions exported by other loaded
packages'
      NAMESPACEs.

For a call from outside a package, the precedence is the same, but
1 and 2 are not relevant.

As far as I can tell, this is the current behaviour except for the
relative ordering of 1 and 2.

Nope. Current behaviour (see details in ?UseMethod) is:

"To support this, UseMethod and NextMethod search for methods in two
places: in the environment in which the generic function is called,
and in the registration data base for the environment in which the
generic is defined".

The issue here is that you are registering a non-standard name
(.gen.formula) for that generic and then defining what would be the
standard name (gen.formula) for... what purpose? IMHO, this is a bad
practice and should be avoided.

The situation initially arose when I wanted to soft-deprecate calling a
particular method by its full name in order to clean up the package's
namespace.

To use our working example, I wanted calls to gen.formula() to issue a
deprecation warning, but calls to gen(formula) not to. The simplest way
to do that that I could find was to create a function, say,
.gen.formula() that would implement the method and declare it as the S3
export, and modify gen.formula() to issue the warning before passing on
to .gen.formula(). Then, direct calls to gen.formula() would produce a
warning, but gen(formula) would by pass it.

That is, for a call from inside a package, the order of precedence
would be as follows:
   1. S3method() in that package's NAMESPACE.
   2. Appropriately named function in that package (exported or
not).
   3. Appropriately named function in calling environment (which
may be
      GlobalEnv).
   4. S3method() in other loaded packages' NAMESPACEs.
   5. Appropriately named functions exported by other loaded
packages'
      NAMESPACEs.

For a call from outside a package, the precedence is the same, but
1 and 2 are not relevant.

As far as I can tell, this is the current behaviour except for the
relative ordering of 1 and 2.

Nope. Current behaviour (see details in ?UseMethod) is:

"To support this, UseMethod and NextMethod search for methods in two
places: in the environment in which the generic function is called,
and in the registration data base for the environment in which the
generic is defined".

Can you be more specific where the sequence above contradicts the
current implementation (except for swapping 1 and 2)? As far as I can
tell, it's just a more concrete description of what's in the
documentation.

IMO the simplest way to do this is to check who the caller was:

foo <- function(x) UseMethod("foo")
foo.bar <- function(x) {
  sc <- sys.call(-1)
  if (is.null(sc) || sc[[1]] != "foo")
    .Deprecated(msg="Calling 'foo.bar' directly is deprecated")
}

x <- 1
class(x) <- "bar"

foo(x)      # silent
foo.bar(x)  # a warning is issued

The description in the documentation means that point 3) in your list
goes always first, which automatically implies 2) if the generic is
defined in the same package.

Hi, Inaki,

On Sun, 2019-05-19 at 16:59 +0200, I?aki Ucar wrote:

IMO the simplest way to do this is to check who the caller was:

foo <- function(x) UseMethod("foo")
foo.bar <- function(x) {
  sc <- sys.call(-1)
  if (is.null(sc) || sc[[1]] != "foo")
    .Deprecated(msg="Calling 'foo.bar' directly is deprecated")
}

x <- 1
class(x) <- "bar"

foo(x)      # silent
foo.bar(x)  # a warning is issued

f <- getS3method("foo","bar")
f(x) # spurious warning

foo.baz <- function(x) NextMethod("foo")
class(x) <- c("baz","bar")
foo(x) # spurious warning

The description in the documentation means that point 3) in your list
goes always first, which automatically implies 2) if the generic is
defined in the same package.

Are you sure which package defines the generic matters? I've just ran
some tests with two packages and moving the generic around doesn't seem
to affect things: the calling function determines whose method is used.

It seems to me like there is no contradiction after all, except that I
propose that the registered method should take precedence within a
namespace.

The only situation in which it would change R's behaviour would be when
a package/namespace contains a function foo.bar() AND a NAMESPACE
containing S3method(foo,bar,not.foo.bar) AND calls foo() on objects of
type bar from inside the package. It is extremely unlikely to break any
existing code.