rlang (version 0.1.6)

lang: 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

# NOT RUN {
# 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")
# }