UserHooks                package:base                R Documentation

_F_u_n_c_t_i_o_n_s _t_o _G_e_t _a_n_d _S_e_t _H_o_o_k_s _f_o_r _L_o_a_d, _A_t_t_a_c_h, _D_e_t_a_c_h _a_n_d _U_n_l_o_a_d

_D_e_s_c_r_i_p_t_i_o_n:

     These functions allow users to set actions to be taken before
     packages are attached/detached and name spaces are (un)loaded.

_U_s_a_g_e:

     getHook(hookName)
     setHook(hookName, value,
             action = c("append", "prepend", "replace"))

     packageEvent(pkgname,
                  event = c("onLoad", "attach", "detach", "onUnload"))

_A_r_g_u_m_e_n_t_s:

hookName: character string: the hook name

 pkgname: character string: the package/name space name.

   event: character string: an event for the package

   value: A function, or for 'action="replace"', 'NULL'.

  action: The action to be taken.  The names can be abbreviated.

_D_e_t_a_i_l_s:

     'setHook' provides a general mechanism for users to register
     hooks, a list of functions to be called from system (or user)
     functions.  The initial set of hooks is associated with events on
     packages/name spaces: these hooks are named via calls to
     'packageEvent'.

     To remove a hook completely, call 'setHook(hookName, NULL,
     "replace")'.

     When an R package is attached by 'library', it can call
     initialization code via a function '.First.lib', and when it is
     'detach'-ed it can tidy up via a function '.Last.lib'. Users can
     add their own initialization code via the hooks provided by these
     functions, functions which will be called as 'funname(pkgname,
     pkgpath)' inside a 'try' call.  (The attach hook is called after
     '.First.lib' and the detach hook before '.Last.lib'.)

     If a package has a name space, there are two further actions, when
     the name space is loaded (before being attached and after
     '.onLoad' is called ) and when it is unloaded (after being
     detached and before '.onUnload').  Note that code in these hooks
     is run without the package being on the search path, so objects in
     the package need to be referred to using the double colon operator
     as in the example. (Unlike '.onLoad', the user hook is run after
     the name space has been sealed.)

     Hooks are normally run in the order shown by 'getHook', but the
     '"detach"' and '"onUnload"' hooks are run in reverse order so the
     default for package events is to add hooks 'inside' existing ones.

     Note that when an R session is finished, packages are not detached
     and name spaces are not unloaded, so the corresponding hooks will
     not be run.

     The hooks are stored in the environment '.userHooksEnv' in the
     base package, with 'mangled' names.

_V_a_l_u_e:

     For 'getHook' function, a list of functions (possible empty). For
     'setHook' function, no return value. For 'packageEvent', the
     derived hook name (a character string).

_S_e_e _A_l_s_o:

     'library', 'detach', 'loadNamespace'.

     Other hooks may be added later: 'plot.new' and 'persp' already
     have them.

_E_x_a_m_p_l_e_s:

     setHook(packageEvent("grDevices", "onLoad"),
             function(...) grDevices::ps.options(horizontal=FALSE))