missing_arg: Generate or handle a missing argument

Description

These functions help using the missing argument as a regular R object.

missing_arg() generates a missing argument.
is_missing() is like base::missing() but also supports testing for missing arguments contained in other objects like lists.
maybe_missing() is useful to pass down an input that might be missing to another function. It avoids triggering an "argument is missing" error.

Usage

missing_arg()
is_missing(x)
maybe_missing(x)

Other ways to reify the missing argument

base::quote(expr = ) is the canonical way to create a missing argument object.
expr() called without argument creates a missing argument.
quo() called without argument creates an empty quosure, i.e. a quosure containing the missing argument object.

Fragility of the missing argument object

The missing argument is an object that triggers an error if and only if it is the result of evaluating a symbol. No error is produced when a function call evaluates to the missing argument object. This means that expressions like x[[1]] <- missing_arg() are perfectly safe. Likewise, x[[1]] is safe even if the result is the missing object.

However, as soon as the missing argument is passed down between functions through an argument, you're at risk of triggering a missing error. This is because arguments are passed through symbols. To work around this, is_missing() and maybe_missing(x) use a bit of magic to determine if the input is the missing argument without triggering a missing error.

maybe_missing() is particularly useful for prototyping meta-programming algorithm in R. The missing argument is a likely input when computing on the language because it is a standard object in formals lists. While C functions are always allowed to return the missing argument and pass it to other C functions, this is not the case on the R side. If you're implementing your meta-programming algorithm in R, use maybe_missing() when an input might be the missing argument object.

[[1]: R:[1 [[1]: R:[1

Life cycle

missing_arg() and is_missing() are stable.
Like the rest of rlang, maybe_missing() is maturing.

Examples

Run this code

# NOT RUN {
# The missing argument usually arises inside a function when the
# user omits an argument that does not have a default:
fn <- function(x) is_missing(x)
fn()

# Creating a missing argument can also be useful to generate calls
args <- list(1, missing_arg(), 3, missing_arg())
quo(fn(!!! args))

# Other ways to create that object include:
quote(expr = )
expr()

# It is perfectly valid to generate and assign the missing
# argument in a list.
x <- missing_arg()
l <- list(missing_arg())

# Just don't evaluate a symbol that contains the empty argument.
# Evaluating the object `x` that we created above would trigger an
# error.
# x  # Not run

# On the other hand accessing a missing argument contained in a
# list does not trigger an error because subsetting is a function
# call:
l[[1]]
is.null(l[[1]])

# In case you really need to access a symbol that might contain the
# empty argument object, use maybe_missing():
maybe_missing(x)
is.null(maybe_missing(x))
is_missing(maybe_missing(x))


# Note that base::missing() only works on symbols and does not
# support complex expressions. For this reason the following lines
# would throw an error:

#> missing(missing_arg())
#> missing(l[[1]])

# while is_missing() will work as expected:
is_missing(missing_arg())
is_missing(l[[1]])
# }