R: Jump to or from a frame

return_from {rlang} | R Documentation

## Jump to or from a frame

### Description

While `base::return()` can only return from the current local frame, these two functions will return from any frame on the current evaluation stack, between the global and the currently active context. They provide a way of performing arbitrary non-local jumps out of the function currently under evaluation.

### Usage

    return_from(frame, value = NULL)

    return_to(frame, value = NULL)

### Arguments

`frame` | An environment, a frame object, or any object with an `get_env()` method. The environment should be an evaluation environment currently on the stack.
`value` | The return value.

### Details

`return_from()` will jump out of `frame`. `return_to()` is a bit trickier. It will jump out of the frame located just before `frame` in the evaluation stack, so that control flow ends up in `frame`, at the location where the previous frame was called from.

These functions should only be used rarely. These sort of non-local gotos can be hard to reason about in casual code, though they can sometimes be useful. Also, consider to use the condition system to perform non-local jumps.

### Life cycle

The support for `frame` object is experimental. The stack and frame objects are likely to be moved from rlang to another package. Please pass simple environments to `return_from()` and `return_to()`.

### Examples

    # Passing fn() evaluation frame to g():
    fn <- function() {
      val <- g(get_env())
      cat("g returned:", val, "\n")
      "normal return"
    }
    g <- function(env) h(env)

    # Here we return from fn() with a new return value:
    h <- function(env) return_from(env, "early return")
    fn()

    # Here we return to fn(). The call stack unwinds until the last frame
    # called by fn(), which is g() in that case.
    h <- function(env) return_to(env, "early return")
    fn()

[Package rlang version 0.2.2 Index]