R: Binding and Environment Locking, Active Bindings

bindenv {base} | R Documentation

## Binding and Environment Locking, Active Bindings

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

### Usage

    lockEnvironment(env, bindings = FALSE)
    environmentIsLocked(env)
    lockBinding(sym, env)
    unlockBinding(sym, env)
    bindingIsLocked(sym, env)

    makeActiveBinding(sym, fun, env)
    bindingIsActive(sym, env)
    activeBindingFunction(sym, env)

### Arguments

`env` | an environment.
`bindings` | logical specifying whether bindings should be locked.
`sym` | a name object or character string.
`fun` | a function taking zero or one arguments.

### Details

The function `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.

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

`makeActiveBinding` installs `fun` in environment `env` so that getting the value of `sym` calls `fun` with no arguments, and assigning to `sym` calls `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 `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 `.onLoad`.

### Value

The `bindingIsLocked` and `environmentIsLocked` return a length-one logical vector. The remaining functions return `NULL`, invisibly.

### Author(s)

Luke Tierney

### 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

[Package base version 4.0.5 Index]