\HeaderA{bindenv}{Binding and Environment Adjustments}{bindenv}
\aliasA{bindingIsActive}{bindenv}{bindingIsActive}
\aliasA{bindingIsLocked}{bindenv}{bindingIsLocked}
\aliasA{environmentIsLocked}{bindenv}{environmentIsLocked}
\aliasA{lockBinding}{bindenv}{lockBinding}
\aliasA{lockEnvironment}{bindenv}{lockEnvironment}
\aliasA{makeActiveBinding}{bindenv}{makeActiveBinding}
\aliasA{unlockBinding}{bindenv}{unlockBinding}
\keyword{utilities}{bindenv}
\begin{Description}\relax
These functions represent an experimental interface for adjustments
to environments and bindings within environments.  They allow for
locking environments as well as individual bindings, and for linking
a variable to a function.
\end{Description}
\begin{Usage}
\begin{verbatim}
lockEnvironment(env, bindings = FALSE)
environmentIsLocked(env)
lockBinding(sym, env)
unlockBinding(sym, env)
bindingIsLocked(sym, env)
makeActiveBinding(sym, fun, env)
bindingIsActive(sym, env)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{env}] an environment.
\item[\code{bindings}] logical specifying whether bindings should be locked.
\item[\code{sym}] a name object or character string
\item[\code{fun}] a function taking zero or one arguments
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The function \code{lockEnvironment} locks its environment argument,
which must be a normal environment (not base).  (Locking the base
environment and name space may be supported later.)  Locking the
environment prevents adding or removing variable bindings from the
environment. Changing the value of a variable is still possible unless
the binding has been locked.  The name space environments of packages
with name spaces are locked when loaded.

\code{lockBinding} locks individual bindings in the specified
environment.  The value of a locked binding cannot be changed. Locked
bindings may be removed from an environment unless the environment is
locked.

\code{makeActiveBinding} installs \code{fun} so that getting the value
of \code{sym} calls \code{fun} with no arguments, and assigning to
\code{sym} calls \code{fun} with one argument, the value to be
assigned.  This allows the implementation of things like C variables
linked to \R{} variables and variables linked to databases.  It may also
be useful for making thread-safe versions of some system globals.
\end{Details}
\begin{Value}
The \code{*isLocked} functions return a length-one logical vector.  The
remaining functions return \code{NULL}, invisibly.
\end{Value}
\begin{Author}\relax
Luke Tierney
\end{Author}
\begin{Examples}
\begin{ExampleCode}
# locking environments
e <- new.env()
assign("x", 1, envir = e)
get("x", envir = e)
lockEnvironment(e)
get("x", envir = e)
assign("x", 2, envir = e)
try(assign("y", 2, envir = e)) # error

# locking bindings
e <- new.env()
assign("x", 1, envir = e)
get("x", envir = e)
lockBinding("x", e)
try(assign("x", 2, envir = e)) # error
unlockBinding("x", e)
assign("x", 2, envir = e)
get("x", envir = e)

# active bindings
f <- local( {
    x <- 1
    function(v) {
       if (missing(v))
           cat("get\n")
       else {
           cat("set\n")
           x <<- v
       }
       x
    }
})
makeActiveBinding("fred", f, .GlobalEnv)
bindingIsActive("fred", .GlobalEnv)
fred
fred <- 2
fred
\end{ExampleCode}
\end{Examples}

