userhooks.Rd 4.18 KB
Newer Older
Radford Neal's avatar
Radford Neal committed
1 2
% File src/library/base/man/userhooks.Rd
% Part of the R package, http://www.R-project.org
3
% Copyright 1995-2009 R Core Team
Radford Neal's avatar
Radford Neal committed
4 5 6 7 8 9 10 11 12 13
% Distributed under GPL 2 or later

\name{userhooks}
\alias{getHook}
\alias{setHook}
\alias{packageEvent}
\alias{.userHooksEnv}
\title{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
Radford Neal's avatar
Radford Neal committed
14
  are attached/detached and namespaces are (un)loaded.
Radford Neal's avatar
Radford Neal committed
15 16 17 18 19 20 21 22 23 24 25
}
\usage{
getHook(hookName)
setHook(hookName, value,
        action = c("append", "prepend", "replace"))

packageEvent(pkgname,
             event = c("onLoad", "attach", "detach", "onUnload"))
}
\arguments{
  \item{hookName}{character string: the hook name}
Radford Neal's avatar
Radford Neal committed
26
  \item{pkgname}{character string: the package/namespace name.}
Radford Neal's avatar
Radford Neal committed
27 28 29 30 31 32 33 34
  \item{event}{character string: an event for the package}
  \item{value}{A function, or for \code{action="replace"}, \code{NULL}.}
  \item{action}{The action to be taken.  The names can be abbreviated.}
}

\details{
  \code{setHook} provides a general mechanism for users to register
  hooks, a list of functions to be called from system (or user)
Radford Neal's avatar
Radford Neal committed
35 36 37
  functions.  The initial set of hooks was associated with events on
  packages/namespaces: these hooks are named via calls to
  \code{packageEvent}.
Radford Neal's avatar
Radford Neal committed
38 39 40

  To remove a hook completely, call \code{setHook(hookName, NULL, "replace")}.
  
Radford Neal's avatar
Radford Neal committed
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62
  When an \R package is attached by \code{\link{library}} or loaded by
  other means, it can call initialization code.  See
  \code{\link{.onLoad}} for a description of the package hook functions
  called during initialization.  Users can add their own initialization
  code via the hooks provided by \code{setHook()}, functions which will
  be called as \code{funname(pkgname, pkgpath)} inside a
  \code{\link{try}} call.
  
  The sequence of events depends on which hooks are defined, and whether
  a package is attached or just loaded.  In the case where all hooks
  are defined and a package is attached, the order of initialization 
  events is as follows:
  \enumerate{
  \item The package namespace is loaded.
  \item The package's \code{\link{.onLoad}} function is run.
  \item The namespace is sealed.
  \item The user's \code{"onLoad"} hook is run.  
  \item The package is added to the search path.
  \item The package's \code{\link{.onAttach}} function is run.
  \item The package environment is sealed.
  \item The user's \code{"attach"} hook is run.
  }
Radford Neal's avatar
Radford Neal committed
63
  
Radford Neal's avatar
Radford Neal committed
64 65 66 67 68 69 70 71 72 73
  A similar sequence (but in reverse) is run when a package is detached
  and its namespace unloaded:
  \enumerate{
  \item The user's \code{"detach"} hook is run.
  \item The package's \code{\link{.Last.lib}} function is run. 
  \item The package is removed from the search path.  
  \item The user's \code{"onUnload"} hook is run.  
  \item The package's \code{\link{.onUnload}} function is run.
  \item The package namespace is unloaded.
  }
Radford Neal's avatar
Radford Neal committed
74
  Note that when an \R session is finished, packages are not detached and
Radford Neal's avatar
Radford Neal committed
75 76 77 78 79 80 81 82 83 84 85 86
  namespaces are not unloaded, so the corresponding hooks will not be
  run.  
  
  Also note that some of the user hooks are run without the package
  being on the search path, so in those hooks objects in the package
  need to be referred to using the double (or triple) colon operator,
  as in the example.
  
  If multiple hooks are added, they are normally run in the order shown
  by \code{getHook}, but the \code{"detach"} and \code{"onUnload"} hooks
  are run in reverse order so the default for package events is to add
  hooks \sQuote{inside} existing ones.
Radford Neal's avatar
Radford Neal committed
87 88 89 90 91

  The hooks are stored in the environment \code{.userHooksEnv} in the
  base package, with \sQuote{mangled} names.
}
\value{
Radford Neal's avatar
Radford Neal committed
92
  For \code{getHook} function, a list of functions (possibly empty).
Radford Neal's avatar
Radford Neal committed
93 94 95 96 97
  For \code{setHook} function, no return value.
  For \code{packageEvent}, the derived hook name (a character string).
}
\seealso{
  \code{\link{library}}, \code{\link{detach}}, \code{\link{loadNamespace}}.
Radford Neal's avatar
Radford Neal committed
98 99 100
  
  See \code{\link{::}}
  for a discussion of the double and triple colon operators. 
Radford Neal's avatar
Radford Neal committed
101

Radford Neal's avatar
Radford Neal committed
102
  Other hooks may be added later: functions \code{\link{plot.new}} and
Radford Neal's avatar
Radford Neal committed
103 104 105 106 107 108 109
  \code{\link{persp}} already have them.
}
\examples{
setHook(packageEvent("grDevices", "onLoad"),
        function(...) grDevices::ps.options(horizontal=FALSE)) 
}
\keyword{utilities}