This help topic is for R version 2.9.0. For the current version of R, try https://stat.ethz.ch/R-manual/R-patched/library/base/html/userhooks.html
UserHooks {base}R Documentation

Functions to Get and Set Hooks for Load, Attach, Detach and Unload

Description

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

Usage

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

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

Arguments

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.

Details

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.

Value

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

See Also

library, detach, loadNamespace.

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

Examples

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

[Package base version 2.9.0 ]