R: Generate or handle a missing argument

missing_arg {rlang} | R Documentation

## 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, potentially substituting by a default value. It avoids triggering an "argument is missing" error.

### Usage

    missing_arg()

    is_missing(x)

    maybe_missing(x, default = missing_arg())

### Arguments

`x` | An object that might be the missing argument.
`default` | The object to return if the input is missing, defaults to `missing_arg()`.

### 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 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.

### Life cycle

- `missing_arg()` and `is_missing()` are stable.

- Like the rest of rlang, `maybe_missing()` is maturing.

### Examples

    # 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]])

[Package rlang version 0.4.3 Index]