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)

Arguments

env the environment.
bindings Logical value: if TRUE, all current bindings in the environment are also locked.
sym the binding name. This is the name of an object stored in an environment. It will be coerced to name (via as.name()) for a character string input.
fun a function with one argument.

Details

When an environment is locked, no bindings can be added to it or removed. However, existing bindings' value can be modified unless they are also locked.
When a binding is locked, its value cannot be changed. It may still be removed from the environment if the environment is not locked.
Active bindings contain a function in their 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 may be useful for mapping external variables, such as C variables or data base entries, to S variables.
Value
environmentIsLocked, bindingIsLocked and bindingIsActive return TRUE if the environment or binding is locked, or binding is active; FALSE otherwise.
The other functions return invisible NULL.
Note
Once an environment has been locked, it cannot be unlocked. Can't make an existing regular binding active.
See Also
invisible
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
Package base version 4.0.0-28
Package Index