bindenv
Binding and Environment Adjustments

Description

Locks an environment and/or its bindings to prevent modifications. Makes an active binding.

Usage

lockEnvironment(env, bindings = FALSE)
environmentIsLocked(env)
lockBinding(sym, env)
unlockBinding(sym, env)
makeActiveBinding(sym, fun, env)
bindingIsLocked(sym, env)
bindingIsActive(sym, env)
activeBindingFunction(sym, env)

Arguments

env the environment.
bindings a logical value. If TRUE, all current bindings in the environment are also locked. The default is FALSE.
sym the name or a character string. The variable name of an object stored in an environment.
fun a function with one argument.

Details

When an environment is locked, no bindings can be added to it or removed from it. However, existing bindings values can be modified, unless they are also locked. When an environment is locked, it cannot be unlocked.
When a binding is locked, its value cannot be changed. It can still be removed from the environment if the environment is not locked.
An active binding contains a function in its value cell. Getting the value of an active binding calls this function with no arguments and returns the result. Assigning to an active binding calls this function with one argument: the new value. Active bindings can be useful for mapping external values, such as C variables or data base entries, to environment variables.
You cannot make an existing regular binding into an active binding. However, you can remove an existing regular binding by calling remove. Then you can create an active binding for that name.
Use activeBindingFunction to retrieve the function called when referring to an active binding.
For the functions lockBinding and unlockBinding, if the specified environment is either the base package environment (baseenv) or the base namespace environment (getNamespace("base")), then the variable is also locked or unlocked in the other environment.
Value
environmentIsLocked returns TRUE if the environment is locked. If not, returns FALSE.
bindingIsLocked returns TRUE if the binding is locked. If not, returns FALSE.
bindingIsActive returns TRUE if the binding is active. If not, returns FALSE.
The other functions return NULL invisibly.
See Also
assign, Assignment, baseenv, remove
Examples
e <- new.env()
environmentIsLocked(e) # FALSE
e$x <- 1
lockEnvironment(e)
environmentIsLocked(e) # TRUE
e$x <- 2 # Can still modify existing binding
#e$y <- 1 # Error: cannot add bindings to a locked environment
#remove("x", envir=e) # Error: cannot remove bindings from a locked environment

bindingIsLocked("x", e) # FALSE
lockBinding("x", e)
bindingIsLocked("x", e) # TRUE
#e$x <- 1 # Error:  cannot change value of locked binding for 'x'

ee <- new.env()
ee$xx <- 1
ee$yy <- 1
lockBinding("xx", ee)
lockBinding("yy", ee)
#ee$xx <- 2 # Error:  cannot change value of locked binding for 'xx'
remove("xx", envir = ee) # Can still remove a locked binding from a unlocked environment.
unlockBinding("yy", ee)
ee$yy <- 2 # OK.

# active bindings
eee <- new.env()
f <- local( {
    x <- 0
    function(y) {
       if (missing(y)) {
           cat("get value\n")
           x
       } else {
           cat("set value\n")
           x <<- as.numeric(y)
       }
    }
})
makeActiveBinding("num", f, eee) 
bindingIsActive("num", eee) # TRUE
eee$num
eee$num <- "1" # coerced to numeric
eee$num # 1 (numeric)

eee$x <- 1
bindingIsActive("x", eee) # FALSE
#makeActiveBinding("x", f, eee) # Error: symbol 'x' already has a regular binding
remove("x",envir=eee)
makeActiveBinding("x", f, eee) # now this works
Package base version 6.1.1-7
Package Index