importDefaults           package:Defaults           R Documentation

_I_m_p_o_r_t _G_l_o_b_a_l _D_e_f_a_u_l_t _A_r_g_u_m_e_n_t _V_a_l_u_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     Use globally specified defaults, if set, in place of formally
     specified default argument values.  Allows user to specify
     function defaults different than formally supplied values, e.g. to
     change poorly performing defaults, or satisfy a different
     preference.

_U_s_a_g_e:

     importDefaults(calling.fun)

_A_r_g_u_m_e_n_t_s:

calling.fun: name of function to act upon 

_D_e_t_a_i_l_s:

     Placed immediately after the function declaration, a call to
     'importDefaults' checks the user's environment for globally
     specified default values for the called function. These defaults
     can be specified by the user with a call to 'setDefaults', and
     will override any default formal parameters, in effect replacing
     the original defaults with user supplied values instead.

     If a function has _not_ been written with 'importDefaults' (most R
     functions, so far...), it is possible to simply call 'useDefaults'
     to achieve the same results. As of version 1.1-0, simply calling
     'setDefaults' will call 'useDefaults' internally, removing the
     need to explicitly call. See the related help page.

     Any values specified by the user in a in the parent function (that
     is, the function containing 'importDefaults') will override the
     values set in the global default environment.

_V_a_l_u_e:

     Used for its side-effects, a call to 'importDefaults' loads all
     non-NULL default values specified by the user into the current
     function's environment, effectively changing the default values
     passed in the parent function call.

     'importDefaults' values, like formally defined defaults in the
     function definition, take lower precedence than arguments
     specified by the user in the function call.

     An alias to 'importDefaults', '.importDefaults' is the actual
     function added when 'useDefaults' is called on a function. The
     naming convention is designed to facilitate setting and unsetting,
     and should _NOT_ be used by the function developer. Please use
     only 'importDefaults'

_N_o_t_e:

     It is important to note that when a function implements
     'importDefaults', non-named arguments _may_ be ignored if a global
     Default has been set (i.e. not NULL).

     If this is the case, simply name the arguments in the calling
     function.

     This _should_ also work for functions retrieving formal parameter
     values from 'options', as it assigns a value to the parameter in a
     way that looks like it was passed in the function call. So any
     check on 'options' would presumably disregard 'importDefaults'
     values if an argument was passed to the function (what
     'useDefaults' does)

_A_u_t_h_o_r(_s):

     Jeffrey A. Ryan

_S_e_e _A_l_s_o:

     'useDefaults','setDefaults'

_E_x_a_m_p_l_e_s:

     my.fun <- function(x=3)
     {
       importDefaults('my.fun')
       x ^ 2
     }

     my.fun()        #returns 9

     setDefaults(my.fun,x=10)
     my.fun()        #returns 100
     my.fun(x=4)     #returns 16

     getDefaults(my.fun)
     formals(my.fun)
     unsetDefaults(my.fun,confirm=FALSE)
     getDefaults(my.fun)

     my.fun()        #returns 9

