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
maybe_missing() is useful to pass down an input that might be
missing to another function, potentially substituting by a
default value. It avoids triggering an "argument is missing" error.
missing_arg() is_missing(x) maybe_missing(x, default = missing_arg())
An object that might be the missing argument.
The object to return if the input is missing,
base::quote(expr = ) is the canonical way to create a missing
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.
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[] <- missing_arg()
are perfectly safe. Likewise,
x[] 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,
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 algorithms 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.
is_missing() are stable.
Like the rest of rlang,
maybe_missing() is maturing.
# 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()#>  TRUE# Creating a missing argument can also be useful to generate calls args <- list(1, missing_arg(), 3, missing_arg()) quo(fn(!!! args))#> <quosure> #> expr: ^fn(1, , 3, ) #> env: 0x77638d8# 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[]#>is.null(l[])#>  FALSE# 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))#>  FALSEis_missing(maybe_missing(x))#>  TRUE# 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[]) # while is_missing() will work as expected: is_missing(missing_arg())#>  TRUEis_missing(l[])#>  TRUE