UserHooks {base} | R Documentation |
These functions allow users to set actions to be taken before packages are attached/detached and namespaces are (un)loaded.
getHook(hookName) setHook(hookName, value, action = c("append", "prepend", "replace")) packageEvent(pkgname, event = c("onLoad", "attach", "detach", "onUnload"))
hookName |
character string: the hook name |
pkgname |
character string: the package/namespace name.
If versioned install has been used, pkgname should be
the unversioned name of the package (but any version information
will be stripped). |
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 appreviated. |
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/namespaces: 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 namespace, there are two further actions, when the
namespace 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 namespaces 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.
For getHook
function, a list of functions (possible empty).
For setHook
function, no return value.
For packageEvent
, the derived hook name (a character string).
library
, detach
, loadNamespace
.
Other hooks may be added later: plot.new
and
persp
already have them.
setHook(packageEvent("grDevices", "onLoad"), function(...) grDevices::ps.options(horizontal=FALSE))