The R Project SVN R

Rev

Rev 88585 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
60325 ripley 1 
% File src/library/methods/man/testInheritedMethods.Rd
68948 ripley 2 
% Part of the R package, https://www.R-project.org
67570 ripley 3 
% Copyright 2009-2015 R Core Team
60325 ripley 4 
% Distributed under GPL 2 or later
5 
 
47740 jmc 6 
\name{testInheritedMethods}
56186 murdoch 7 
\alias{testInheritedMethods}
47740 jmc 8 
\alias{MethodSelectionReport-class}
9 
\alias{.Other-class}
10 
\title{
11 
Test for and Report about  Selection of Inherited Methods
12 
}
13 
\description{
50418 ripley 14 
  A set of distinct inherited signatures is generated to test
15 
  inheritance for all the methods of a specified generic function.  If
16 
  method selection is ambiguous for some of these, a summary of the
17 
  ambiguities is attached to the returned object.  This test should be
18 
  performed by package authors \emph{before} releasing a package.
47740 jmc 19 
}
20 
\usage{
50418 ripley 21 
testInheritedMethods(f, signatures, test = TRUE, virtual = FALSE,
22 
                     groupMethods = TRUE, where = .GlobalEnv)
47740 jmc 23 
}
24 
\arguments{
50418 ripley 25 
  \item{f}{a generic function or the character string name of one.  By default,
26 
    all currently defined subclasses of all the method signatures for this
27 
    generic will be examined.  The other arguments are mainly options to
28 
    modify which inheritance patterns will be examined.
29 
  }
47740 jmc 30 
  \item{signatures}{
50418 ripley 31 
    An optional set of subclass signatures to use instead of the relevant
32 
    subclasses computed by \code{testInheritedMethods}.  See the Details
33 
    for how this is done.  This argument might be supplied after a call
34 
    with \code{test = FALSE}, to test selection in batches.
35 
  }
47740 jmc 36 
  \item{test}{
50418 ripley 37 
    optional flag to control whether method selection is actually tested.
38 
    If \code{FALSE}, returns just the list of relevant signatures for
39 
    subclasses, without calling \code{\link{selectMethod}} for each signature.
40 
    If there are a very large number of signatures, you may want to collect the full list  and then test them in batches.
41 
  }
47740 jmc 42 
  \item{virtual}{
50418 ripley 43 
    should virtual classes be included in the relevant subclasses.
44 
    Normally not, since only the classes of actual arguments will trigger
45 
    the inheritance calculation in a call to the generic function.
46 
    Including virtual classes may be useful if the class has no current
47 
    non-virtual subclasses but you anticipate your users may define such
48 
    classes in the future.
47740 jmc 49 
}
50 
  \item{groupMethods}{
50418 ripley 51 
    should methods for the group generic function be included?
52 
  }
47740 jmc 53 
  \item{where}{
50418 ripley 54 
    the environment in which to look for class definitions.  Nearly
55 
    always, use the default global environment after attaching all the
56 
    packages with relevant methods and/or class definitions.
57 
  }
47740 jmc 58 
}
59 
\details{
50418 ripley 60 
  The following description applies when the optional arguments are
61 
  omitted, the usual case.
62 
  First, the defining signatures for all methods are computed by calls
63 
  to \code{\link{findMethodSignatures}}.
64 
  From these all the known non-virtual subclasses are found for each
65 
  class that appears in the signature of some method.
66 
  These subclasses are split into groups according to which class they
67 
  inherit from, and only one subclass from each group is retained (for
68 
  each argument in the generic signature).
69 
  So if a method was defined with class \code{"vector"} for some
70 
  argument, one actual vector class is chosen arbitrarily.
71 
  The case of \code{"ANY"} is dealt with specially, since all classes
72 
  extend it.  A dummy, nonvirtual class, \code{".Other"}, is used to
73 
  correspond to all classes that have no superclasses among those being
74 
  tested.
47740 jmc 75 
 
50418 ripley 76 
  All combinations of retained subclasses for the
77 
  arguments in the generic signature are then computed.
78 
  Each row of the resulting matrix is a signature to be tested by a call
79 
  to \code{\link{selectMethod}}.
80 
  To collect information on ambiguous selections,
81 
  \code{testInheritedMethods} establishes a calling handler for the
82 
  special signal \code{"ambiguousMethodSelection"}, by setting the
83 
  corresponding option.
47740 jmc 84 
}
85 
\value{
50418 ripley 86 
  An object of class \code{"methodSelectionReport"}.  The details of
87 
  this class are currently subject to change.  It has slots
88 
  \code{"target"}, \code{"selected"}, \code{"candidates"}, and
89 
  \code{"note"}, all referring to the ambiguous cases (and so of length
90 
 
91 
  programmer to detect and preferably fix ambiguous method selections.
92 
  The object contains in addition slots \code{"generic"}, the name of
93 
  the generic function, and
94 
  \code{"allSelections"},  giving the vector of labels for all
95 
  the signatures tested.
47740 jmc 96 
}
97 
\references{
88585 hornik 98 
  \bibshow{R:Chambers:2008}
99 
  (Section 10.6 for basics of method selection.)
47740 jmc 100 
 
88589 hornik 101 
  \bibshow{R:Chambers:2009}
47740 jmc 102 
}
103 
\examples{
56287 ripley 104 
## if no other attached packages have methods for `+` or its group
105 
## generic functions, this returns a 16 by 2 matrix of selection
106 
## patterns (in R 2.9.0)
50418 ripley 107 
testInheritedMethods("+")
47740 jmc 108 
}
109 
 
110 
\keyword{programming}
111 
\keyword{classes}
112 
\keyword{methods}