GenericFunctions           package:methods           R Documentation

_T_o_o_l_s _f_o_r _M_a_n_a_g_i_n_g _G_e_n_e_r_i_c _F_u_n_c_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

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

     dumpMethod(f, signature, file, where, def)
     findFunction(f, generic = TRUE, where = topenv(parent.frame()))
     dumpMethods(f, file, signature, methods, where)
     signature(...)

     removeMethods(f, where = topenv(parent.frame()), all = TRUE)
     setReplaceMethod(f, ..., where = topenv(parent.frame()))

     getGenerics(where, searchForm = FALSE)
     allGenerics(where, searchForm = FALSE)
     callGeneric(...)

_A_r_g_u_m_e_n_t_s:

       f: The character string naming the function. 

   where: The environment, namespace, or search-list position from
          which to search for objects.  By default, start at the
          top-level environment of the calling function, typically the
          global environment (i.e., use the search list), or the
          namespace of a package from which the call came.  It is
          important to supply this argument when calling any of these
          functions indirectly.  With package namespaces, the default
          is likely to be wrong in such calls.

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). 

     all: in 'removeMethods', logical indicating if all (default) or
          only the first method found should be removed.

searchForm: In 'getGenerics', if 'TRUE', the 'package' slot of the
          returned result is in the form used by 'search()', otherwise
          as the simple package name (e.g, '"package:base"' vs
          '"base"'). 

_S_u_m_m_a_r_y _o_f _F_u_n_c_t_i_o_n_s:

     '_i_s_G_e_n_e_r_i_c': 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, anywhere in the
          current search list, or in the specified position 'where'. 
          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.


     '_r_e_m_o_v_e_G_e_n_e_r_i_c', '_r_e_m_o_v_e_M_e_t_h_o_d_s': Remove all the methods for the
          generic function of this name.  In addition, 'removeGeneric'
          removes the function itself; 'removeMethods' restores the
          non-generic function which was the default method.   If there
          was no default method, 'removeMethods' leaves a generic
          function with no methods.

     '_s_t_a_n_d_a_r_d_G_e_n_e_r_i_c': Dispatches a method from the current function
          call for the generic function 'f'.  It is an error to call
          'standardGeneric' anywhere except in the body of the
          corresponding generic function.

          Note that 'standardGeneric' is a primitive function in the
          'base' package for efficiency  reasons, but rather documented
          here where it belongs naturally.

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

     '_f_i_n_d_F_u_n_c_t_i_o_n': return a list of either the positions on the
          search list, or the current top-level environment, on which a
          function object for 'name' exists.  The returned value is
          _always_ a list, use the first element to access the first
          visible version of the function.  See the example.

          _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.  Also, 'findFunction' works
          correctly in the code for a package when attaching the
          package via a call to 'library'.

     '_d_u_m_p_M_e_t_h_o_d_s': Dump all the methods for this generic.

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

     '_g_e_t_G_e_n_e_r_i_c_s': Returns the names of the generic functions that
          have methods defined on 'where'; this argument can be an
          environment or an index into the search list.  By default,
          the whole search list is used.

          The methods definitions are stored with package qualifiers;
          for example, methods for function '"initialize"' might refer
          to two different functions of that name, on different
          packages.  The package names corresponding to the method list
          object are contained in the slot 'package' of the returned
          object.  The form of the returned name can be plain (e.g.,
          '"base"'), or in the form used in the search list
          ('"package:base"') according to the value of 'searchForm'

     '_c_a_l_l_G_e_n_e_r_i_c': 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.  If the generic is a
          primitive then arguments must be supplied.

_D_e_t_a_i_l_s:

     '_s_e_t_G_e_n_e_r_i_c': 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.

     '_i_s_G_e_n_e_r_i_c': 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.)

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

     '_s_t_a_n_d_a_r_d_G_e_n_e_r_i_c': 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'.

     '_d_u_m_p_M_e_t_h_o_d': The resulting source file will recreate the method.

     '_f_i_n_d_F_u_n_c_t_i_o_n': If 'generic' is 'FALSE', ignore generic functions.

     '_d_u_m_p_M_e_t_h_o_d_s': 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.)

     '_s_i_g_n_a_t_u_r_e': 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.

     '_r_e_m_o_v_e_M_e_t_h_o_d_s': 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, the generic function remains but with no methods
          (so any call to it will generate an error).  In either case,
          a following call to 'setMethod' will consistently
          re-establish the same generic function as before.

_R_e_f_e_r_e_n_c_e_s:

     The R package 'methods' implements, with a few exceptions, the
     programming interface for classes and methods in the book
     _Programming with Data_ (John M. Chambers, Springer, 1998), in
     particular sections 1.6, 2.7, 2.8, and chapters 7 and 8.

     While the programming interface for the methods package follows
     the reference, the R software is an original implementation, so
     details in the reference that reflect the S4 implementation may
     appear differently in R.  Also, there are extensions to the
     programming interface developed more recently than the reference. 
     For a discussion of details see '?Methods' and the links from that
     documentation.

_S_e_e _A_l_s_o:

     'getMethod' (also for 'selectMethod'), 'setGeneric', 'setClass',
     'showMethods'

_E_x_a_m_p_l_e_s:

     require(stats) # for lm

     ## get the function "myFun" -- throw an error if 0 or > 1 versions visible:
     findFuncStrict <- function(fName) {
       allF <- findFunction(fName)
       if(length(allF) == 0)
         stop("No versions of ",fName," visible")
       else if(length(allF) > 1)
         stop(fName," is ambiguous: ", length(allF), " versions")
       else
         get(fName, allF[[1]])
     }

     try(findFuncStrict("myFun"))# Error: no version
     lm <- function(x) x+1
     try(findFuncStrict("lm"))#    Error: 2 versions
     findFuncStrict("findFuncStrict")# just 1 version
     rm(lm)

