R: Binding and Environment Adjustments

bindenv {base} | R Documentation

## Binding and Environment Adjustments

### Description

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.

### Usage

    lockEnvironment(env, bindings = FALSE)
    environmentIsLocked(env)
    lockBinding(sym, env)
    unlockBinding(sym, env)
    bindingIsLocked(sym, env)
    makeActiveBinding(sym, fun, env)
    bindingIsActive(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 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.

`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` 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. It may also be useful for making thread-safe versions of some system globals.

### Value

The `*isLocked` funtions 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 2.8.1 Index]