Skip to contents

Get information about currently bound arguments.

Source: R/shortcut.R
shortcut.Rd

These are shortcut methods for querying current bindings. For example, arg_env(x) is equivalent to env(arg(x)), is_forced(x, y) is equivalent to forced(arg_list(x,y)), dots_exprs(...) is equivalent to exprs(dots(...)), and so on. The shortcut forms skip the construction of the intermediate quotation objects.

dots_exprs(...) quotes its arguments and returns a list of expressions. It is equivalent to exprs(dots(...)) (and is nearly equivalent to alist(...), one difference being that dots_exprs will expand ....)

is_literal(x) returns TRUE if an argument x could be a source literal. Specifically it tests whether x is bound to a singleton vector or a missing_value. This check happens without forcing x.

is_missing(...) checks whether an argument is missing, without forcing. It is similar to missing but can take multiple arguments, and can be called in more situations, such as from a nested inner function.

is_missing_(syms, envs) is a normally evaluating version of is_missing. syms should be a symbol, character vector or list of such. envs should be an environment, or list of environments. Vector recycling rules apply, so you can call with a vector of names and one env, or vice versa.

is_promise returns TRUE if the given variable is bound to a promise. Not all arguments are bound to promises; byte-compiled code often omits creating a promise for literal or missing arguments.

is_default determines whether an argument is bound to the function's default value for that argument. It must be called before the arguments have been forced (afterwards it will return FALSE).

Usage

arg_env(sym, env = arg_env_(quote(sym), environment()))

arg_env_(sym, env = arg_env_(quote(sym), environment()))

arg_expr(sym, env = arg_env_(quote(sym), environment()))

arg_expr_(sym, env = arg_env_(quote(sym), environment()))

arg_value(
  sym,
  env = arg_env_(quote(sym), environment()),
  ifnotforced = stop("Variable is not forced, so has no value")
)

arg_value_(
  sym,
  env = arg_env_(quote(sym), environment()),
  ifnotforced = stop("Variable is not forced, so has no value")
)

dots_envs(...)

dots_exprs(...)

is_forced(...)

is_forced_(syms, envs)

is_literal(...)

is_literal_(syms, envs)

is_missing(...)

is_missing_(syms, envs, unwrap = TRUE)

# S3 method for quotation
is_missing_(syms, ..., unwrap = TRUE)

is_promise(...)

is_promise_(syms, envs)

# S3 method for quotation
is_promise_(syms, ...)

is_default(...)

is_default_(syms, envs)

# S3 method for quotation
is_default_(syms, ...)

Arguments

sym

For plain arg_env, etc, a bare name, which is quoted. For the underscore versions arg_env_, something that evaluates to a name or character.

env

The environment to search in.

ifnotforced

What to return if calling arg_value on a promise that has not been forced.

...

Bare variable names (for is_*) or expressions (for dots_*). Not forced.

syms

A character vector or list of symbols.

envs

An environment or list of environments.

unwrap

Whether to recursively unwrap before testing for missingness.

Value

arg_env returns an environment.

arg_expr returns the expression bound to a named argument.

arg_value returns the value bound to a named argument.

is_forced and other is_* return a logical vector with optional names.

Details

Throughout this package, some functions come in two forms, a "bare" version which quotes its first argument literally, and a normally-evaluating version with a trailing underscore in its name. So is_forced(x) chiecks whether "x" is a missing variable, while is_forced_(x, environment()) checks whether "x" contains the name of another variable which is missing. The following are all equivalent:

  • arg_env(x)

  • {y <- quo(x); arg_env_(y)}

  • arg_env_(quote(x), environment())

  • arg_env_(quo(x))

  • env(arg_(quo(x))).

When used with quotation objects, the is_*_ functions with trailing underscore work at one level of indirection compared to quotation methods. For example, missing_(x) tests whether expr(x) is [missing_value()], whereas is_missing_(x) assumes expr(x) is a name and checks if that name refers to a variable that is missing. The following are equivalent:

  • is_missing(x)

  • is_missing_(quo(x))

  • missing_(arg(x))

When used with a quotation or dots, is_missing(q) looks for the variable(s) specified by expr(q) in environment env(q)]`.