setGeneric              package:methods              R Documentation

_D_e_f_i_n_e _a _N_e_w _G_e_n_e_r_i_c _F_u_n_c_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     Create a new generic function of the given name, for which formal
     methods can then be defined.  Typically, an existing non-generic
     function becomes the default method, but there is much optional
     control.  See the details section.

_U_s_a_g_e:

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

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

_A_r_g_u_m_e_n_t_s:

    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'.  The body will be set to the standard dispatch
          mechanism, unless you want to do something different (use
          argument `myDispatch' in this case.

          Note that `def' is not the default method; use argument
          `useAsDefault' if you want to specify the default separately. 

   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 vector or unevaluated  expression. 
          The value returned by the generic function must have (or
          extend) this class, or one of the classes; otherwise, an
          error is generated.  See the details section for supplying an
          expression. 

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

doAssign: You can supply `doAssign' as `TRUE' to force assigning a
          generic function even if one already exists. See the details
          section. The rule of not assigning generics for primitives
          cannot be overriden by setting `doAssign' to `TRUE'. 

myDispatch: Normally, the body of a generic function does nothing
          except to dispatch methods (via a call to `standardGeneric').
           The evaluation model, however, allows the generic to do any
          other computation it wants, it it calls `standardGeneric' at
          some point.  Otherwise, `setGeneric' will ignore the body of
          the supplied generic unless `myDispatch' is set to `TRUE'.
          See the details section. 

useAsDefault: Override the usual choice of default argument (an
          existing non-generic function or no default if there is no
          such function). Argument `useAsDefault' can be supplied,
          either as a function to use for the default, or as a logical
          value. `FALSE' says not to have a default method at all, so
          that an error occurs if there is not an explicit or inherited
          method for a call. `TRUE' says to use the existing function
          as default, unconditionally (hardly ever needed as an
          explicit argument). See the section on details. 

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. 

_D_e_t_a_i_l_s:

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

     The simplest and most common situation is that `name' is already
     an ordinary non-generic function, and you now want to turn this
     function into a generic. In this case you will most often supply
     only `name'.  The existing function becomes the default method,
     and the special `group' and `valueClass' properties remain
     unspecified.

     A second situation is that you want to create a new, generic
     function, unrelated to any existing function.  In this case, you
     need to supply a skeleton of the function definition, to define
     the arguments for the function.  The body of a generic function is
     usually a standard form, `standardGeneric(name)' where `name' is
     the quoted name of the generic function.

     When calling `setGeneric' in this form, you would normally supply
     the `def' argument as a function of this form.  If not told
     otherwise, `setGeneric' will try to find a non-generic version of
     the function to use as a default.  If you don't want this to
     happen, supply the argument `useAsDefault'.  That argument can be
     the function you want to be the default method.  You can supply
     the argument as `FALSE' to force no default (i.e., to cause an
     error if there is not direct or inherited method on call to the
     function).

     The same no-default situation occurs if there is no non-generic
     form of the function, and `useAsDefault' does not supply one. 
     Remember, though, you can also just assign the default you want
     (even one that generates an error) rather than relying on the
     prior situation.

     Usually, calling `setGeneric' if there is already a generic
     function of this name has no effect.  If you want to force a new
     definition, supply `doAssign = TRUE' (but it would be cleaner in
     most cases to remove the old generic before creating the new one;
     see `removeGeneric').  There is one absolute restriction:  you
     cannot create an explicit generic for the primitive functions in
     the base library.  These are dispatched from C code for efficiency
     and, also, are implicitly not to be redefined in any case.

     As mentioned, the body of a generic function usually does nothing
     except for dispatching methods by a call to `standardGeneric'.
     Under some circumstances you might just want to do some additional
     computation in the generic function itself.  As long as your
     function eventually calls `standardGeneric' that is permissible
     (though perhaps not a good idea, in that it makes the behavior of
     your function different from the usual S model).  If your function
     does not call `standardGeneric' you are in trouble, because none
     of the methods for the function will ever be dispatched.  The
     computations in `setGeneric' look for such a call, and normally
     ignore the body of a `def' argument that has no such call.  If you
     really need to supply such a definition (perhaps because you call
     something else that calls `standardGeneric'), you can force the
     use of `def' by supplying `myDispatch = TRUE'. By default, the
     generic function can return any object.

     If `valueClass' is supplied, it can be either a vector of class
     names or an unevaluated expression.  If an unevaluated expression
     is supplied (e.g., by using `quote'), the expression will be
     evaluated in the frame of the call to the generic function, after
     the method is dispatched.  Therefore, the expression can involve
     any argument or locally defined object in that frame. The test is
     done in the form `is(object, class)', so that a value from a class
     that extends a supplied value class will be accepted. An empty
     (i.e., zero length) vector of classes means anything is allowed
     (but it would be clearer programming to have an expression that
     evaluated to `"ANY"').

     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.

_V_a_l_u_e:

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

_A_u_t_h_o_r(_s):

     John Chambers

_R_e_f_e_r_e_n_c_e_s:

     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.

_S_e_e _A_l_s_o:

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

