UserHooks                package:base                R Documentation

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

Description:

     These function allow users to set actions to be taken before
     packages are attached/detached and namespaces 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/namespace name. If versioned
          install has been used, 'pkgname' should the unversioned name
          of the package and 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.

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/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 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.

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("graphics", "onLoad"),
             function(...) graphics::ps.options(horizontal=FALSE)) 

