ns-hooks                package:base                R Documentation

_H_o_o_k_s _f_o_r _N_a_m_e _S_p_a_c_e _e_v_e_n_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     Packages with name spaces can supply functions to be called when
     loaded, attached or unloaded.

_U_s_a_g_e:

     .onLoad(libname, pkgname)
     .onAttach(libname, pkgname)
     .onUnload(libpath)

_A_r_g_u_m_e_n_t_s:

 libname: a character string giving the library directory where the
          package defining the namespace was found.

 pkgname: a character string giving the name of the package.

 libpath: a character string giving the complete path to the package.

_D_e_t_a_i_l_s:

     These functions apply only to packages with name spaces.

     After loading, 'loadNamespace' looks for a hook function named
     '.onLoad' and runs it before sealing the namespace and processing
     exports.

     If a name space is unloaded (via 'unloadNamespace'), a hook
     function '.onUnload' is run before final unloading.

     Note that the code in '.onLoad' and '.onUnload' is run without the
     package being on the search path, but (unless circumvented)
     lexical scope will make objects in the namespace and its imports
     visible. (Do not use the double colon operator in '.onLoad' as
     exports have not been processed at the point it is run.)

     When the package is attached (via 'library'), the hook function
     '.onAttach' is looked for and if found is called after the
     exported functions are attached and before the package environment
     is sealed.  This is less likely to be useful than '.onLoad', which
     should be seen as the analogue of '.First.lib' (which is only used
     for packages without a name space).

     '.onLoad', '.onUnload' and '.onAttach' are looked for as internal
     variables in the name space and should not be exported.

     If a function '.Last.lib' is visible in the package, it will be
     called when the package is detached: this does need to be
     exported.

     Anything needed for the functioning of the name space should be
     handled at load/unload times by the '.onLoad' and '.onUnload'
     hooks.  For example, DLLs can be loaded (unless done by a
     'useDynLib' directive in the 'NAMESPACE' file) and initialized in
     '.onLoad' and unloaded in '.onUnload'.  Use '.onAttach' only for
     actions that are needed only when the package becomes visible to
     the user, for example a start-up message.

     If a package was installed with '--with-package-versions', the
     'pkgname' supplied will be something like 'tree_1.0-16'.

_S_e_e _A_l_s_o:

     'setHook' shows how users can set hooks on the same events.