RMethodUtils             package:methods             R Documentation

_M_e_t_h_o_d _U_t_i_l_i_t_i_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     Utility functions to support the definition and use of formal
     methods.  Most of these functions will not normally be called
     directly by the user.

_U_s_a_g_e:

     getGeneric(f, mustFind=FALSE, where, package)

     getGroup(fdef, recursive, where)
     getGroupMembers(group, recursive = FALSE, character = TRUE)

     getMethodsMetaData(f, where)
     assignMethodsMetaData (f, value, fdef, where, deflt)

     makeGeneric(f, fdef, fdefault =, group=list(), valueClass=character(),
                 package =, signature = NULL, genericFunction = NULL,
                 simpleInheritanceOnly = NULL)

     makeStandardGeneric(f, fdef)

     generic.skeleton(name, fdef, fdefault)

     defaultDumpName(generic, signature)

     doPrimitiveMethod(name, def, call= sys.call(sys.parent()),
                       ev = sys.frame(sys.parent(2)))

     conformMethod(signature, mnames, fnames, f= , fdef, method)

     matchSignature(signature, fun, where)

     findUnique(what, message, where)

     MethodAddCoerce(method, argName, thisClass, methodClass)

     cacheMetaData(where, attach = TRUE, searchWhere =  as.environment(where),
                   doCheck=TRUE)

     cacheGenericsMetaData(f, fdef, attach = TRUE, where, package, methods)

     setPrimitiveMethods(f, fdef, code, generic, mlist)

     missingArg(symbol, envir = parent.frame(), eval)

     balanceMethodsList(mlist, args, check = TRUE)

     sigToEnv(signature, generic)

     rematchDefinition(definition, generic, mnames, fnames, signature)
     unRematchDefinition(definition)

     asMethodDefinition(def, signature, sealed = FALSE, fdef)

     addNextMethod(method, f, mlist, optional, envir)

_S_u_m_m_a_r_y _o_f _F_u_n_c_t_i_o_n_s:



     '_g_e_t_G_e_n_e_r_i_c': returns the definition of the function named 'f' as
          a generic.

          If no definition is found, throws an error or returns 'NULL'
          according to the value of 'mustFind'.  By default, searches
          in the top-level environment (normally the global
          environment, but adjusted to work correctly when package code
          is evaluated from the function 'library').

          Primitive functions are dealt with specially, since there is
          never a formal generic definition for them.  The value
          returned is the formal definition used for assigning methods
          to this primitive. Not all primitives can have methods; if
          this one can't, then 'getGeneric' returns 'NULL' or throws an
          error.


     '_g_e_t_G_r_o_u_p': returns the groups to which this generic belongs,
          searching from environment 'where' (the global environment
          normally by default).

          If 'recursive=TRUE', also all the group(s) of these groups.


     '_g_e_t_G_r_o_u_p_M_e_m_b_e_r_s': Return all the members of the group generic
          function named 'group'. If 'recursive' is 'TRUE', and some
          members are group generics, includes their members as well.
          If 'character' is 'TRUE', returns just a character vector of
          the names; otherwise returns a list, whose elements may (or
          may not) include either names with a package attribute or
          actual generic functions.

          Note that members that are not defined as generic functions
          will _not_ be included in the returned value.  To see the raw
          data, use 'getGeneric(group)@groupMembers'.


     '_g_e_t_M_e_t_h_o_d_s_M_e_t_a_D_a_t_a', '_a_s_s_i_g_n_M_e_t_h_o_d_s_M_e_t_a_D_a_t_a', '_m_l_i_s_t_M_e_t_a_N_a_m_e': 
          Utilities to get ('getMethodsMetaData') and assign
          ('assignMethodsMetaData') the metadata object recording the
          methods defined in a particular package, or to return the
          mangled name for that object  ('mlistMetaName').

          The assign function should not be used directly.  The get
          function may be useful if you want explicitly only the
          outcome of the methods assigned in this package.  Otherwise,
          use 'getMethods'.


     '_m_a_t_c_h_S_i_g_n_a_t_u_r_e': Matches the signature object (a partially or
          completely named subset of the signature arguments of the
          generic function object 'fun'), and return a vector of all
          the classes in the order specified by 'fun@signature'.  The
          classes not specified by 'signature' will be '"ANY"' in the
          value, but extra trailing '"ANY"''s are removed.  When the
          input signature is empty, the returned signature is a single
          '"ANY"' matching the first formal argument (so the returned
          value is always non-empty).

          Generates an error if any of the supplied signature names are
          not legal; that is, not in the signature slot of the generic
          function.

          If argument 'where' is supplied, a warning will be issued if
          any of the classes does not have a formal definition visible
          from 'where'.


     '_M_e_t_h_o_d_A_d_d_C_o_e_r_c_e': Possibly modify one or more methods to
          explicitly coerce this argument to 'methodClass', the class
          for which the method is explicitly defined.  Only modifies
          the method if an explicit coerce is required to coerce from
          'thisClass' to 'methodClass'.


     '_f_i_n_d_U_n_i_q_u_e': Return the list of environments (or equivalent)
          having an object named 'what', using environment 'where' and
          its parent environments.  If more than one is found, a
          warning message is generated, using 'message' to identify
          what was being searched for, unless 'message' is the empty
          string.


     '_c_a_c_h_e_M_e_t_a_D_a_t_a', '_c_a_c_h_e_G_e_n_e_r_i_c_s_M_e_t_a_D_a_t_a', '_s_e_t_P_r_i_m_i_t_i_v_e_M_e_t_h_o_d_s': 
          Utilities for ensuring that the internal information about
          class and method definitions is up to date.  Should normally
          be called automatically whenever needed (for example, when a
          method or class definition changes, or when a package is
          attached or detached).  Required primarily because primitive
          functions are dispatched in C code, rather than by the
          official model.

          The 'setPrimitiveMethods' function resets the caching
          information for a particular primitive function.  Don't call
          it directly.


     '_m_i_s_s_i_n_g_A_r_g': Returns 'TRUE' if the symbol supplied is missing
          _from the call_ corresponding to the environment supplied (by
          default, environment of the call to 'missingArg').  If 'eval'
          is true, the argument is evaluated to get the name of the
          symbol to test.  Note that 'missingArg' is closer to the
          'Blue Book' sense of the 'missing' function, not that of the
          current R base package implementation.  But beware that it
          works reliably only if no assignment has yet been made to the
          argument.  (For method dispatch this is fine, because
          computations are done at the beginning of the call.)


     '_b_a_l_a_n_c_e_M_e_t_h_o_d_s_L_i_s_t': Called from 'setMethod' to ensure that all
          nodes in the list have the same depth (i.e., the same number
          of levels of arguments).  Balance is needed to ensure that
          all necessary arguments are examined when inherited methods
          are being found and added to the 'allMethods' slot.  No
          actual recomputation is needed usually except when a new
          method uses a longer signature than has appeared before.

          Balance requires that _all_ methods be added to the generic
          via 'setMethod' (how else could you do it?) or by the initial
          'setGeneric' call converting the ordinary function.


     '_s_i_g_T_o_E_n_v': Turn the signature (a named vector of classes) into an
          environment with the classes assigned to the names.  The
          environment is then suitable for calling 'MethodsListSelect',
          with 'evalArgs=FALSE', to select a method corresponding to
          the signature.  Usually not called directly: see
          'selectMethod'.


     '._s_a_v_e_I_m_a_g_e': Flag, used in dynamically initializing the methods
          package from '.First.lib'


     '_r_e_m_a_t_c_h_D_e_f_i_n_i_t_i_o_n', '_u_n_R_e_m_a_t_c_h_D_e_f_i_n_i_t_i_o_n': If the specified
          method in a call to 'setMethod' specializes the argument list
          (by replacing ...), then 'rematchDefinition' constructs the
          actual method stored. Using knowledge of how
          'rematchDefinition' works, 'unRematchDefinition' reverses the
          procedure; if given a function or method definition that does
          not correspond to this form, it just returns its argument.


     '_a_s_M_e_t_h_o_d_D_e_f_i_n_i_t_i_o_n': Turn a function definition into an object of
          class 'MethodDefinition', corresponding to the given
          'signature' (by default generates a default method with empty
          signature).  The definition is sealed according to the
          'sealed' argument.


     '_a_d_d_N_e_x_t_M_e_t_h_o_d': A generic function that finds the next method for
          the signature of the method definition 'method'  and caches
          that method in the method definition (promoting the class to
          '"MethodWithNext"'.  Note that argument 'mlist' is obsolete
          and not used.


     '_m_a_k_e_G_e_n_e_r_i_c': Makes a generic function object corresponding to
          the given function name, optional definition and optional
          default method. Other arguments supply optional elements for
          the slots of class 'genericFunction'.


     '_m_a_k_e_S_t_a_n_d_a_r_d_G_e_n_e_r_i_c': a utility function that makes a valid
          function calling 'standardGeneric' for name 'f'.  Works (more
          or less) even if the actual definition, 'fdef', is not a
          proper function, that is, it's a primitive or internal.


     '_c_o_n_f_o_r_m_M_e_t_h_o_d': If the formal arguments, 'mnames', are not
          identical to the formal arguments to the function, 'fnames',
          'conformMethod' determines whether the signature and the two
          sets of arguments conform, and returns the signature,
          possibly extended.  The function name, 'f' is supplied for
          error messages. The generic function, 'fdef', supplies the
          generic signature  for matching purposes.

          The method assignment conforms if either method and function
          have identical formal argument lists.  It can also conform if
          the method omits some of the formal arguments of the function
          but: (1) the non-omitted arguments are a subset of the
          function arguments, appearing in the same order; (2) there
          are no arguments to the method that are not arguments to the
          function;  (3) the omitted formal arguments do not appear as
          explicit classes in the signature; and (4) the omitted
          arguments are not used as local names or function names in
          the body of the method.


     '_d_e_f_a_u_l_t_D_u_m_p_N_a_m_e': the default name to be used for dumping a
          method.


     '_d_o_P_r_i_m_i_t_i_v_e_M_e_t_h_o_d': do a primitive call to builtin function
          'name' the definition and call provided, and carried out in
          the environment 'ev'.

          A call to 'doPrimitiveMethod' is used when the actual method
          is a .Primitive.  (Because primitives don't behave correctly
          as ordinary functions, not having either formal arguments nor
          a function body).


_S_e_e _A_l_s_o:

     'setGeneric', 'setClass', 'showMethods'.

_E_x_a_m_p_l_e_s:

     getGroup("exp")
     getGroup("==", recursive = TRUE)

     getGroupMembers("Arith")
     getGroupMembers("Math")
     getGroupMembers("Ops") # -> its sub groups