setGeneric              package:methods              R Documentation

Define a New Generic Function

Description:

     Create a new generic function of the given name, for which formal
     methods can then be defined.

Usage:

     setGeneric(name, def, group=NULL, valueClass=NULL, where=1, doAssign)

     setGroupGeneric(name, def, group=NULL, valueClass=NULL, knownMembers, where=1)

Arguments:

    name: The character string name of the generic function.  In the
          simplest and most common case, a function of this name is
          already defined.  The existing function may be non-generic or
          already a generic (see the details). 

     def: An optional function object, defining the generic.  This
          argument is usually only needed (and is then required) if
          there is no current function of this name. In that case, the
          formal arguments and default values for the generic are taken
          from `def'.  See also argument `useAsDefault'. 

   group: Optionally, a character string giving the group of generic
          functions to which this function belongs.  Methods can be
          defined for the corresponding group generic, and these will
          then define methods for this specific generic function, if no
          method has been explicitly defined for the corresponding
          signature.  See the references for more discussion. 

valueClass: An optional character string defining the class to asserted
          to be given to the value returned by this generic function.
          By default, the generic function can return any object. (At
          the moment, the assertion supplied in this argument is not
          enforced or checked.) 

   where: Where to store the resulting initial methods definition, and
          possibly the generic function; by default, stored into the
          global environment. 

doAssign: Should a new generic version of the function be assigned? 
          The default action depends on whether a generic version
          currently exists.  If not, one will be assigned to `where',
          except that primitive functions in the base package are never
          turned into explicit generic functions (they are dispatched
          from the internal code in the evaluator).

          You can supply `doAssign' as `TRUE' to force assigning a
          generic function even if one already exists, or as `FALSE' to
          prevent assigning the generic in any case (for example,
          because you know one exists on another package).  But the
          rule of not assigning generics for primitives cannot be
          overriden by setting `doAssign' to `TRUE'. 

knownMembers: (For `setGroupGeneric' only)  The names of functions that
          are known to be members of this group.  This information is
          used to reset cached definitions of the member generics when
          information about the group generic is changed. 

Details:

     The `setGeneric' function is called to initialize a generic
     function in an environment (usually the global environment), as
     prepartion for defining some methods for that function.

     The simplest and most common situation is that `name' is already a
     function, either an ordinary non-generic function or else a
     generic function in another environment.  In the second case,
     essentially all you will be doing is to make a copy of the
     existing generic, without its methods, in the current environment.
      Only the `name' argument will be used.  The new generic must
     agree with the current one in essentially everything except for
     the methods defined.

     The other simple and common situation is that you already have a
     non-generic function (probably in the same place you plan to save
     the generic), and now want to turn this function into a generic. 
     In this case, too, you will most often supply only `name'.  The
     existing function becomes the default method, and the special
     `group' and `valueClass' properties remain unspecified.

     The `setGroupGeneric' function behaves like `setGeneric' except
     that it constructs a group generic function, differing in two ways
     from an ordinary generic function.  First, this function cannot be
     called directly, and the body of the function created will contain
     a stop call with this information.  Second, the group generic
     function contains information about the known members of the
     group, used to keep the members up to date when the group
     definition changes, through changes in the search list or direct
     specification of methods, etc.

Value:

     The `setGeneric' function exists for its side effect:  saving the
     generic function to allow methods to be specified later.  It
     returns `name'.

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:

     `Methods' for a discussion of other functions to specify and
     manipulate the methods of generic functions.

