R: Create a call

lang {rlang} | R Documentation

## Create a call

### Description

Language objects are (with symbols) one of the two types of symbolic objects in R. These symbolic objects form the backbone of expressions. They represent a value, unlike literal objects which are their own values. While symbols are directly bound to a value, language objects represent function calls, which is why they are commonly referred to as calls.

- `lang()` creates a call from a function name (or a literal function to inline in the call) and a list of arguments.

- `new_language()` is bare-bones and takes a head and a tail. The head must be callable and the tail must be a pairlist. See section on calls as parse trees below. This constructor is useful to avoid costly coercions between lists and pairlists of arguments.

### Usage

    lang(.fn, ..., .ns = NULL)

    new_language(head, tail = NULL)

### Arguments

`.fn` | Function to call. Must be a callable object: a string, symbol, call, or a function.
`...` | Arguments to the call either in or out of a list. Dots are evaluated with explicit splicing.
`.ns` | Namespace with which to prefix `.fn`. Must be a string or symbol.
`head` | A callable object: a symbol, call, or literal function.
`tail` | A pairlist of arguments.

### Calls as parse tree

Language objects are structurally identical to pairlists. They are containers of two objects, the head and the tail (also called the CAR and the CDR).

- The head contains the function to call, either literally or symbolically. If a literal function, the call is said to be inlined. If a symbol, the call is named. If another call, it is recursive. `foo()()` would be an example of a recursive call whose head contains another call. See `lang_type_of()` and `is_callable()`.

- The tail contains the arguments and must be a pairlist.

You can retrieve those components with `lang_head()` and `lang_tail()`. Since language nodes can contain other nodes (either calls or pairlists), they are capable of forming a tree. When R parses an expression, it saves the parse tree in a data structure composed of language and pairlist nodes. It is precisely because the parse tree is saved in first-class R objects that it is possible for functions to capture their arguments unevaluated.

### Call versus language

`call` is the old S mode of these objects while `language` is the R type. While it is usually better to avoid using S terminology, it would probably be even more confusing to systematically refer to "calls" as "language". rlang still uses `lang` as particle for function dealing with calls for consistency.

### See Also

lang_modify

### Examples

    # fn can either be a string, a symbol or a call
    lang("f", a = 1)
    lang(quote(f), a = 1)
    lang(quote(f()), a = 1)

    #' Can supply arguments individually or in a list
    lang(quote(f), a = 1, b = 2)
    lang(quote(f), splice(list(a = 1, b = 2)))

    # Creating namespaced calls:
    lang("fun", arg = quote(baz), .ns = "mypkg")

[Package rlang version 0.1.6 Index]