src/library/base/man/bindenv.Rd

% File src/library/base/man/bindenv.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2018 R Core Team
% Distributed under GPL 2 or later

\name{bindenv}
\title{Binding and Environment Locking, Active Bindings}
\usage{
lockEnvironment(env, bindings = FALSE)
environmentIsLocked(env)
lockBinding(sym, env)
unlockBinding(sym, env)
bindingIsLocked(sym, env)

makeActiveBinding(sym, fun, env)
bindingIsActive(sym, env)
}
\alias{bindenv}
\alias{lockEnvironment}
\alias{environmentIsLocked}
\alias{lockBinding}
\alias{unlockBinding}
\alias{makeActiveBinding}
\alias{bindingIsLocked}
\alias{bindingIsActive}
\arguments{
  \item{env}{an environment.}
  \item{bindings}{logical specifying whether bindings should be locked.}
  \item{sym}{a name object or character string.}
  \item{fun}{a function taking zero or one arguments.}
}
\description{
  These functions represent an 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.
}
\details{
  The function \code{lockEnvironment} locks its environment argument,
  which must be a normal environment (not base).  (Locking the base
  environment and namespace 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 namespace environments of packages
  with namespaces 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} in environment \code{env}
  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, and is used to implement \code{\link{setRefClass}}.  It may
  also be useful for making thread-safe versions of some system globals.
  Currently active bindings are not preserved during package installation,
  but they can be created in \code{\link{.onLoad}}.
}
\value{
  The \code{bindingIsLocked} and \code{environmentIsLocked} return a
  length-one logical vector.  The remaining functions return
  \code{NULL}, invisibly.
}
\examples{
# 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
}
\keyword{utilities}
\author{Luke Tierney}