GenericFunctions           package:methods           R Documentation

Tools for Managing Generic Functions

Description:

     The functions documented here manage collections of methods
     associated with a generic function, as well as providing
     information about the generic functions themselves.

Usage:

     isGeneric(f, where, fdef, getName = FALSE)

     isGroup(f, where, fdef)

     removeGeneric(f, where)

     standardGeneric(f)

     dumpMethod(f, signature, file, where, def)

     existsFunction(f, generic = TRUE, where)

     findFunction(f, generic=TRUE)

     dumpMethods(f, file, signature, methods, where)

     signature(...)

     removeMethods(f, where)

     setReplaceMethod(f, ...)

     getGenerics(where)

     allGenerics(where)

     callGeneric(...)

Arguments:

       f: The character string naming the function. 

   where: Where on the search list of attached packages to look for
          functions or methods.  By default, use the whole search list
          to find the relevant object(s).  

signature: The class signature of the relevant method.  A signature is
          a named or unnamed vector of character strings.  If named,
          the names must be formal argument names for the generic
          function.  If `signature' is unnamed, the default is to use
          the first `length(signature)' formal arguments of the
          function. 

    file: The file on which to dump method definitions. 

     def: The function object defining the method; if omitted, the
          current method definition corresponding to the signature. 

     ...: Named or unnamed arguments to form a signature.

 generic: In testing or finding functions, should generic functions be
          included.  Supply as `FALSE' to get only non-generic
          functions.

    fdef: Optional, the generic function definition.

          Usually omitted in calls to `isGeneric'

 getName: If `TRUE', `isGeneric' returns the name of the generic.  By
          default, it returns `TRUE'. 

 methods: The methods object containing the methods to be dumped.  By
          default, the methods defined for this generic (optionally on
          the specified `where' location). 

Summary of Functions:

     `isGeneric': Is there a function named `f', and if so, is it a
          generic?

          The `getName' argument allows a function to find the name
          from a function definition.  If it is `TRUE' then the name of
          the generic is returned, or `FALSE' if this is not a generic
          function definition.

          The behavior of `isGeneric' and `getGeneric' for primitive
          functions is slightly different.  These functions don't exist
          as formal function objects (for efficiency and historical
          reasons), regardless of whether methods have been defined for
          them. A call to `isGeneric' tells you whether methods have
          been defined for this primitive function, either on database
          `where' or anywhere in the current search list.  In contrast,
          a call to `getGeneric' will return what the generic for that
          function would be, even if no methods have been currently
          defined for it.


     `removeGeneric': Remove the generic function of this name.  

     `standardGeneric': Dispatches a method from the current function
          call for the generic function `fname'.  


     `getMethods': The list of methods for the specified generic.  


     `dumpMethod': Dump the method for this generic function and
          signature.  


     `existsFunction': Is there a function of this name. If
          `generic==FALSE', generic functions are not counted.


     `findFunction': return all the elements of the search list on
          which a function definition for `name' exists.

          NOTE: Use this rather than `find' with `mode="function"',
          which is not as meaningful, and has a few subtle bugs from
          its use of regular expressions.


     `selectMethod': Returns the method (a function) that R would use
          to evaluate a call to this generic, with arguments
          corresponding to the specified signature.

          f = the name of the generic function sig = the signature of
          classes to match to the arguments of f.  


     `dumpMethods': Dump all the methods for this generic.  

     `signature': Returns a named list of classes to be matched to
          arguments of a generic function.


     `callGeneric': In the body of a method, this function will make a
          call to the current generic function.  If no arguments are
          passed to `callGeneric', the arguments to the current call
          are passed down; otherwise, the arguments are interpreted as
          in a call to the generic function.


Details:


     `setGeneric': If there is already a non-generic function of this
          name, it will be used to define the generic unless `def' is
          supplied, and the current function will become the default
          method for the generic.

          If `def' is supplied, this defines the generic function, and
          no default method will exist (often a good feature, if the
          function should only be available for a meaningful subset of
          all objects).

          Arguments `group' and `valueClass' are retained for
          consistency with S-Plus, but are currently not used.


     `isGeneric': If the `fdef' argument is supplied, take this as the
          definition of the generic, and test whether it is really a
          generic, with `f' as the name of the generic.  (This argument
          is not available in S-Plus.)


     `removeGeneric': If `where' supplied, just remove the version on
          this element of the search list; otherwise, removes the first
          version encountered.


     `standardGeneric': Generic functions should usually have a call to
          `standardGeneric' as their entire body.  They can, however,
          do any other computations as well.

          The usual `setGeneric' (directly or through calling
          `setMethod') creates a function with a call to
          `standardGeneric'.


     `getMethods': If the function is not a generic function, returns
          NULL.   The `f' argument can be either the character string
          name of the generic or the object itself

          The `where' argument optionally says where to look for the
          function, if `f' is given as the name.


     `dumpMethod': The resulting source file will recreate the method.


     `findFunction': If `generic' is FALSE, ignore generic functions.


     `selectMethod': The vector of strings for the classes can be named
          or not.  If named, the names must match formal argument names
          of f.  If not named, the signature is assumed to apply to the
          arguments of f in order. mustFind = If TRUE, an error results
          if there is no method (or no unique method) corresponding to
          this signature.  Otherwise may return NULL or a MethodsList
          object.


     `dumpMethods': If `signature' is supplied only the methods
          matching this initial signature are dumped.  (This feature is
          not found in S-Plus:  don't use it if you want
          compatibility.)


     `signature': The advantage of using `signature' is to provide a
          check on which arguments you meant, as well as clearer
          documentation in your method specification.  In addition,
          `signature' checks that each of the elements is a single
          character string.


     `removeMethods': Returns `TRUE' if `f' was a generic function,
          `FALSE' (silently) otherwise.

          If there is a default method, the function will be
          re-assigned as a simple function with this definition;
          otherwise, it will be removed.  The assignment or removal can
          be controlled by optional argument `where', which defaults to
          the first element of the search list having a function called
          `f'.

Author(s):

     John Chambers

References:

     The web page <URL: http://www.omegahat.org/RSMethods/index.html>
     is the primary documentation.

     The functions in this package emulate the facility for classes and
     methods described in Programming with Data, (John M. Chambers,
     Springer, 1998).  See this book for further details and examples.

See Also:

     `setGeneric', `setClass', `showMethods'

