useDefaults             package:Defaults             R Documentation

_E_n_a_b_l_e _a_n_d _D_i_s_a_b_l_e _G_l_o_b_a_l _D_e_f_a_u_l_t_s _B_y _F_u_n_c_t_i_o_n

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

     Allows for the use of globally managed default values for formal
     function arguments. Adds the ability to pre-specify a value for
     any formal argument as if it were specified in the function call.

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

     useDefaults(name)
     unDefaults(name)

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

    name: name of function, quoted or unquoted 

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

     These functions are called automatically during calls to
     'setDefaults' and 'unsetDefaults', though they may be called by
     the user as well.

     Defaults are set inside the named function with a call to
     'importDefaults'.  This may be hard coded into the function by the
     author, or may be dynamically added with a call to 'useDefaults'.

     Internally, a new call to 'importDefaults' is added before the
     body of the function 'name'. This is added in the first occurence
     of the specified function encountered in the search path. That is,
     if there are two function objects, the first encountered will be
     modified. The modification takes place in the environment of the
     original function, so namespaces are retained.

     'useDefaults' replaces all formal functional arguments with all
     non-NULL globally specified ones after first checking that these
     global defaults have not been overridden with new values in the
     function  call.

     The order of lookup is as follows, with the lookup halted once a
     specified value is found:

    1. Check for arguments specified  in the actual call

    2. Check for arguments specified by setDefaults

    3. Use original function defaults. (if any)

     Setting default values is accompished via 'setDefaults', with the
     values being written to R's 'options' list as a named list set to
     the function's name appended with a .Default, all managed
     automatically.  It is possible to view and delete all defaults
     with the functions 'getDefaults' and 'unsetDefaults', 
     respectively. All R objects can be saved to the Defaults list,
     with the exception of 'NULL', as this removes the argument from
     the Defaults list instead.

     To return a function enabled by 'useDefaults' to its original
     state, call 'unDefaults'. Conceptually this is similar to 'debug'
     and 'undebug', though implemented entirely in R. The current
     implementation borrows from the R function 'trace' and more
     directly, Mark V. Bravington's 'mtrace'.

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

     None. Called for its side effect of enabling or disabling the
     Defaults mechanism. The only use visible side-effect is the
     modified function body.

_N_o_t_e:

     The underlying 'importDefaults' mechanism relies on the calling
     function to have the same name as function in which it is located.
     This is the case in almost all circumstances, excepting one - when
     called as the passed FUN object in an lapply or similar call, as
     the calling function will then simply be 'FUN' or something
     similar. In these circumstances the function will behave as if
     'useDefaults' had _not_ been called on it, i.e. no check of global
     Defaults will be occur. If Defaults behavior is desired, simply
     create an anonymous function wrapper to the function in question,
     as this will then resolve correctly.

     A special thanks to John Chambers and Dirk Eddelbuettel for
     providing guidance on handling functions using namespaces, as well
     as pointing out the original mishandling of namespace issues.

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

     Jeffrey A. Ryan

_R_e_f_e_r_e_n_c_e_s:

     Mark V. Bravington (2005) _ debug: MVB's debugger for R _, R
     package version 1.1.0

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

     'importDefaults', 'setDefaults', 'formals', 'body', 'as.function'

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

     my.fun <- function(x=2,y=1) { x ^ y }
     my.fun()            #returns 2
     my.fun(x=2,y=10)    #returns 1024

     setDefaults(my.fun,x=2,y=3)
     useDefaults(my.fun)
     my.fun

     my.fun()            #returns 8
     my.fun(y=10)        #returns 1024
     my.fun(x=2,y=10)    #returns 1024

     unDefaults(my.fun)
     my.fun
     my.fun()            #returns 2

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

