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:

     makeGeneric(f, fdef, keepMethods=TRUE, useAsDefault=NA,
                 group=character(), valueClass=character())

     makeStandardGeneric(f, fdef)

     generic.skeleton(name, fdef, fdefault)

     defaultDumpName(generic, signature)

     getAllMethods(f, libs=search())

     setAllMethodsSlot(mlist)

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

     conformMethod(signature, mnames, fnames)

     getGeneric(f, mustFind=FALSE)

     getGroup(fdef, recursive=FALSE)

     getGroupMembers(f, fdef = getGeneric(f))
     setGroupMembers(f, members, fdef = getGeneric(f))

     matchSignature(names, signature, fun)

     ## manage method metadata
     getFromMethodMetaData(name)

     assignToMethodMetaData(name, value)

     removeFromMethodMetaData(name)

     removeMethodsObject(f, where)

     findUnique(what, doFind, message)

     MethodAddCoerce(method, argName, thisClass, methodClass)

     is.primitive(fdef)

     copyEnvironment(object, exceptions)

     cacheMetaData(envir, attach = TRUE)

     cacheGenericsMetaData(generics, attach = TRUE, envir)

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

     printNoClass(x, digits, quote, na.print, print.gap, right, ...)

     print.default(x, ...)

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

     balanceMethodsList(mlist, args, check = TRUE)

     sigToEnv(signature)

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

_S_u_m_m_a_r_y _o_f _F_u_n_c_t_i_o_n_s:


     `_m_a_k_e_G_e_n_e_r_i_c': Makes a generic function object corresponding to
          the given function name and optional definition.


     `_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 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 versions of `f' on the specified
          packages (anything on the current search path by default).

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


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

          If there is no definition in the current search list, throws
          an error or returns NULL according to the value of mustFind.

          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.  

          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', `_s_e_t_G_r_o_u_p_M_e_m_b_e_r_s': Get or set the known members
          of the group generic function `f'.


     `_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 arguments of `fun'), and
          return a vector of all the classes in the order specified by
          `names'.  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).

          The formal arguments of `fun' must agree with `names'
          (usually the formal arguments of the generic function) as
          well, and `matchSignature' checks this.


     `_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 manage methods list objects in a particular
          environment. Not to be called directly.


     `_g_e_t_F_r_o_m_M_e_t_h_o_d_M_e_t_a_D_a_t_a', `_a_s_s_i_g_n_T_o_M_e_t_h_o_d_M_e_t_a_D_a_t_a', `_r_e_m_o_v_e_F_r_o_m_M_e_t_h_o_d_M_e_t_a_D_a_t_a' Funct
          ions to manage the session metadata for methods.  Don't call
          these directly.


     `_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': Find the first position on the search list
          containing object `what'; if more than one is found, a
          warning message is generated, using `message' to identify
          what was being searched for.

          If `doFind' is supplied, it's the version of `find' used to
          do the search (e.g., `findFunction'.


     `_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 session-scope 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.

          The `environment' must be one of the environments on the
          current search list; note in particular that even on
          detaching (`attach=FALSE'), the environment will normally
          still be on the search list.

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


     `_p_r_i_n_t_N_o_C_l_a_s_s',`_p_r_i_n_t._d_e_f_a_u_l_t':  `printNoClass' is equivalent to
          the version of `print.default' in the base package.  The
          methods package overrides the latter function to provide
          meaningful printing for formally defined classes, and
          `printNoClass' is used to get the original default printing.


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

