RMethodUtils             package:methods             R Documentation

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

     getGroup(fdef, recursive, where)

     getMethodsMetaData(f, where)
     assignMethodsMetaData (f, value, fdef, where, deflt)
     mlistMetaName (name, package)

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

     makeStandardGeneric(f, fdef)

     generic.skeleton(name, fdef, fdefault)

     defaultDumpName(generic, signature)

     getAllMethods(f, fdef, where)

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

     conformMethod(signature, mnames, fnames, f)

     matchSignature(signature, fun, where)

     removeMethodsObject(f, where)

     findUnique(what, message, where)

     MethodAddCoerce(method, argName, thisClass, methodClass)

     is.primitive(fdef)

     cacheMetaData(where, attach = TRUE, searchWhere)

     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, genericSig)

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

     asMethodDefinition(def, signature, sealed = FALSE)

     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': return 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': return 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_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': Ut
          ilities 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'.


     '_i_s._p_r_i_m_i_t_i_v_e': Is this object a primitive function (either a
          builtin or special)?


     '_r_e_m_o_v_e_M_e_t_h_o_d_s_O_b_j_e_c_t': remove the metadata object containing
          methods for 'f'.


     '_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': U
          tilities 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 begining 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 a
          'MethodDefinition-class' object, 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 in
          'mlist' corresponding the method definition 'method'  and
          adds the method to the methods list, which it then returns. 
          It uses methods defined suitably for ordinary methods and for
          methods with calls to 'callNextMethod'.


'_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
     'genericFunction-class'.


'_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 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; and (3) the omitted
     formal arguments do not appear as explicit classes in the
     signature.


'_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.


'_g_e_t_A_l_l_M_e_t_h_o_d_s': A generic function (with methods) representing the
     merge of all the methods defined for this generic starting from
     environment 'where', including all parent environments.  By
     default, uses the global environment (and therefore all packages
     on the search list).  This function exists largely to re-compute
     the full set of methods when a change to the available methods
     occurs.  Since all such recomputations are supposed to be
     automatic, direct calls to 'getAllMethods' should not be needed.

     If the generic 'f' has a group generic, methods for this group
     generic (and further generations of group generics, if any) are
     also merged.

     The merging rule is as follows: each generic is merged across
     packages, and the group generics are then merged, finally adding
     the directly defined methods of 'f'.

     The effect of the merging rule is that any method directly defined
     for 'f' on any included package overrides a method for the same
     signature defined for the group generic; similarly for the group
     generic and its group, if any, etc.

     For 'f' or for a specific group generic, methods override in the
     order of the packages being searched.  A method for a particular
     signature on a particular package overrides any methods for the
     same signature on packages later on in the list of packages being
     searched.

     The slot '"allMethods"' of the merged methods list is set to a
     copy of the methods slot; this is the slot where inherited methods
     are stored.


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

