% File src/library/base/man/userhooks.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2015 R Core Team
% 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
  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{
  \item{hookName}{character string: the hook name}
  \item{pkgname}{character string: the package/namespace name}
  \item{event}{character string: an event for the package.  Can be abbreviated.}
  \item{value}{A function or a list of functions, or for \code{action = "replace"}, \code{NULL} }
  \item{action}{The action to be taken.  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)
  functions.  The initial set of hooks was associated with events on
  packages/namespaces: these hooks are named via calls to
  \code{packageEvent}.

  To remove a hook completely, call \code{setHook(hookName, NULL, "replace")}.

  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 If S4 methods dispatch is on, any actions set by
  \code{\link{setLoadAction}} are 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.
  }

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

  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.

  The hooks are stored in the environment \code{.userHooksEnv} in the
  base package, with \sQuote{mangled} names.
}

\value{
  For \code{getHook} function, a list of functions (possibly empty).
  For \code{setHook} function, no return value.
  For \code{packageEvent}, the derived hook name (a character string).
}

\note{
  Hooks need to be set before the event they modify: for standard
  packages this can be problematic as \pkg{methods} is loaded and
  attached early in the startup sequence.   The usual place to set hooks
  such as the example below is in the \file{.Rprofile} file, but that
  will not work for \pkg{methods}.
}

\seealso{
  \code{\link{library}}, \code{\link{detach}}, \code{\link{loadNamespace}}.

  See \code{\link{::}}
  for a discussion of the double and triple colon operators.

  Other hooks may be added later: functions \code{\link{plot.new}} and
  \code{\link{persp}} already have them.
}
\examples{
setHook(packageEvent("grDevices", "onLoad"),
        function(...) grDevices::ps.options(horizontal = FALSE))
}
\keyword{utilities}