shortcut: Get information about currently bound arguments.

In nseval: Tools for Lazy and Non-Standard Evaluation

Get information about currently bound arguments.

Description

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()))

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 class 'quotation'
is_missing_(syms, ..., unwrap = TRUE)

is_promise(...)

is_promise_(syms, envs)

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

is_default(...)

is_default_(syms, envs)

## S3 method for class '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.
...	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.

Details

Throughout this package, some functions come in two forms, a "bare" version which quote their 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)]'.

Value

arg_env returns an environment.

arg_expr returns the expression bound to a named argument.

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

nseval documentation built on Dec. 8, 2022, 9:13 a.m.