rlang/ 0000755 0001762 0000144 00000000000 14176703326 011366 5 ustar ligges users rlang/NAMESPACE 0000644 0001762 0000144 00000026242 14176517033 012611 0 ustar ligges users # Generated by roxygen2: do not edit by hand
S3method("$",rlang_ctxt_pronoun)
S3method("$",rlang_data_pronoun)
S3method("$",rlang_fake_data_pronoun)
S3method("$<-",quosures)
S3method("$<-",rlang_ctxt_pronoun)
S3method("$<-",rlang_data_pronoun)
S3method("[","rlang:::list_of_conditions")
S3method("[",quosure)
S3method("[",quosures)
S3method("[",rlang_ctxt_pronoun)
S3method("[",rlang_data_pronoun)
S3method("[",rlang_envs)
S3method("[",rlib_bytes)
S3method("[<-",quosures)
S3method("[[",quosure)
S3method("[[",rlang_ctxt_pronoun)
S3method("[[",rlang_data_pronoun)
S3method("[[",rlang_fake_data_pronoun)
S3method("[[",rlib_bytes)
S3method("[[<-",quosures)
S3method("[[<-",rlang_ctxt_pronoun)
S3method("[[<-",rlang_data_pronoun)
S3method(Math,quosure)
S3method(Ops,quosure)
S3method(Ops,rlib_bytes)
S3method(Summary,quosure)
S3method(as.character,quosure)
S3method(as.character,rlang_error)
S3method(as.character,rlang_message)
S3method(as.character,rlang_warning)
S3method(as.character,rlib_bytes)
S3method(as.list,quosures)
S3method(as_bytes,character)
S3method(as_bytes,numeric)
S3method(as_bytes,rlib_bytes)
S3method(c,quosures)
S3method(c,rlang_envs)
S3method(cnd_body,default)
S3method(cnd_footer,default)
S3method(cnd_header,default)
S3method(cnd_header,rlib_error_package_not_found)
S3method(conditionMessage,rlang_error)
S3method(conditionMessage,rlang_message)
S3method(conditionMessage,rlang_warning)
S3method(dimnames,rlang_data_pronoun)
S3method(format,rlang_error)
S3method(format,rlang_message)
S3method(format,rlang_trace)
S3method(format,rlang_warning)
S3method(format,rlib_bytes)
S3method(length,rlang_ctxt_pronoun)
S3method(length,rlang_data_pronoun)
S3method(length,rlang_fake_data_pronoun)
S3method(max,rlib_bytes)
S3method(mean,quosure)
S3method(median,quosure)
S3method(min,rlib_bytes)
S3method(names,rlang_ctxt_pronoun)
S3method(names,rlang_data_pronoun)
S3method(names,rlang_fake_data_pronoun)
S3method(print,"rlang:::list_of_conditions")
S3method(print,quosure)
S3method(print,quosures)
S3method(print,rlang_box_done)
S3method(print,rlang_box_splice)
S3method(print,rlang_data_pronoun)
S3method(print,rlang_dict)
S3method(print,rlang_dyn_array)
S3method(print,rlang_envs)
S3method(print,rlang_error)
S3method(print,rlang_fake_data_pronoun)
S3method(print,rlang_lambda_function)
S3method(print,rlang_message)
S3method(print,rlang_trace)
S3method(print,rlang_warning)
S3method(print,rlang_zap)
S3method(print,rlib_bytes)
S3method(quantile,quosure)
S3method(rlang_type_sum,Date)
S3method(rlang_type_sum,POSIXct)
S3method(rlang_type_sum,data.frame)
S3method(rlang_type_sum,default)
S3method(rlang_type_sum,difftime)
S3method(rlang_type_sum,factor)
S3method(rlang_type_sum,ordered)
S3method(str,quosure)
S3method(str,rlang_data_pronoun)
S3method(str,rlang_envs)
S3method(sum,rlib_bytes)
S3method(summary,"rlang:::list_of_conditions")
S3method(summary,rlang_error)
S3method(summary,rlang_message)
S3method(summary,rlang_trace)
S3method(summary,rlang_warning)
export("!!!")
export("!!")
export("%<~%")
export("%@%")
export("%@%<-")
export("%|%")
export("%||%")
export(":=")
export("f_env<-")
export("f_lhs<-")
export("f_rhs<-")
export("fn_body<-")
export("fn_env<-")
export("fn_fmls<-")
export("fn_fmls_names<-")
export("names2<-")
export(.data)
export(.env)
export(UQ)
export(UQS)
export(abort)
export(are_na)
export(arg_match)
export(arg_match0)
export(as_box)
export(as_box_if)
export(as_bytes)
export(as_character)
export(as_closure)
export(as_complex)
export(as_data_mask)
export(as_data_pronoun)
export(as_double)
export(as_environment)
export(as_function)
export(as_integer)
export(as_label)
export(as_list)
export(as_logical)
export(as_name)
export(as_quosure)
export(as_quosures)
export(as_string)
export(as_utf8_character)
export(base_env)
export(bytes)
export(call2)
export(call_args)
export(call_args_names)
export(call_fn)
export(call_inspect)
export(call_match)
export(call_modify)
export(call_name)
export(call_ns)
export(call_standardise)
export(caller_arg)
export(caller_call)
export(caller_env)
export(caller_fn)
export(calling)
export(catch_cnd)
export(check_dots_empty)
export(check_dots_empty0)
export(check_dots_unnamed)
export(check_dots_used)
export(check_exclusive)
export(check_installed)
export(check_required)
export(child_env)
export(chr)
export(chr_unserialise_unicode)
export(cnd)
export(cnd_body)
export(cnd_entrace)
export(cnd_footer)
export(cnd_header)
export(cnd_inherits)
export(cnd_message)
export(cnd_muffle)
export(cnd_signal)
export(cnd_type)
export(coerce_class)
export(coerce_type)
export(cpl)
export(ctxt_frame)
export(current_call)
export(current_env)
export(current_fn)
export(data_sym)
export(data_syms)
export(dbl)
export(done)
export(dots_list)
export(dots_n)
export(dots_splice)
export(dots_values)
export(duplicate)
export(empty_env)
export(enexpr)
export(enexprs)
export(englue)
export(enquo)
export(enquo0)
export(enquos)
export(enquos0)
export(ensym)
export(ensyms)
export(entrace)
export(env)
export(env_bind)
export(env_bind_active)
export(env_bind_lazy)
export(env_binding_are_active)
export(env_binding_are_lazy)
export(env_binding_are_locked)
export(env_binding_lock)
export(env_binding_unlock)
export(env_browse)
export(env_bury)
export(env_cache)
export(env_clone)
export(env_depth)
export(env_get)
export(env_get_list)
export(env_has)
export(env_inherits)
export(env_is_browsed)
export(env_is_locked)
export(env_label)
export(env_length)
export(env_lock)
export(env_name)
export(env_names)
export(env_parent)
export(env_parents)
export(env_poke)
export(env_poke_parent)
export(env_print)
export(env_tail)
export(env_unbind)
export(env_unlock)
export(error_cnd)
export(eval_bare)
export(eval_tidy)
export(exec)
export(exiting)
export(expr)
export(expr_deparse)
export(expr_interp)
export(expr_label)
export(expr_name)
export(expr_print)
export(expr_text)
export(exprs)
export(exprs_auto_name)
export(f_env)
export(f_label)
export(f_lhs)
export(f_name)
export(f_rhs)
export(f_text)
export(flatten)
export(flatten_chr)
export(flatten_cpl)
export(flatten_dbl)
export(flatten_if)
export(flatten_int)
export(flatten_lgl)
export(flatten_raw)
export(fn_body)
export(fn_env)
export(fn_fmls)
export(fn_fmls_names)
export(fn_fmls_syms)
export(format_error_bullets)
export(format_error_call)
export(frame_call)
export(frame_fn)
export(friendly_type)
export(get_env)
export(get_expr)
export(global_entrace)
export(global_env)
export(global_frame)
export(global_handle)
export(global_prompt_install)
export(has_length)
export(has_name)
export(hash)
export(hash_file)
export(have_name)
export(inform)
export(inherits_all)
export(inherits_any)
export(inherits_only)
export(inject)
export(int)
export(int_along)
export(interrupt)
export(invoke)
export(is_atomic)
export(is_attached)
export(is_bare_atomic)
export(is_bare_bytes)
export(is_bare_character)
export(is_bare_complex)
export(is_bare_double)
export(is_bare_environment)
export(is_bare_formula)
export(is_bare_integer)
export(is_bare_integerish)
export(is_bare_list)
export(is_bare_logical)
export(is_bare_numeric)
export(is_bare_raw)
export(is_bare_string)
export(is_bare_vector)
export(is_bool)
export(is_box)
export(is_bytes)
export(is_call)
export(is_call_simple)
export(is_callable)
export(is_character)
export(is_chr_na)
export(is_closure)
export(is_complex)
export(is_condition)
export(is_copyable)
export(is_cpl_na)
export(is_dbl_na)
export(is_dictionaryish)
export(is_done_box)
export(is_double)
export(is_empty)
export(is_environment)
export(is_error)
export(is_expression)
export(is_false)
export(is_formula)
export(is_function)
export(is_installed)
export(is_int_na)
export(is_integer)
export(is_integerish)
export(is_interactive)
export(is_lambda)
export(is_lang)
export(is_lgl_na)
export(is_list)
export(is_logical)
export(is_message)
export(is_missing)
export(is_na)
export(is_named)
export(is_named2)
export(is_namespace)
export(is_node)
export(is_node_list)
export(is_null)
export(is_pairlist)
export(is_primitive)
export(is_primitive_eager)
export(is_primitive_lazy)
export(is_quosure)
export(is_quosures)
export(is_raw)
export(is_reference)
export(is_scalar_atomic)
export(is_scalar_bytes)
export(is_scalar_character)
export(is_scalar_complex)
export(is_scalar_double)
export(is_scalar_integer)
export(is_scalar_integerish)
export(is_scalar_list)
export(is_scalar_logical)
export(is_scalar_raw)
export(is_scalar_vector)
export(is_scoped)
export(is_spliced)
export(is_spliced_bare)
export(is_string)
export(is_symbol)
export(is_symbolic)
export(is_syntactic_literal)
export(is_true)
export(is_vector)
export(is_warning)
export(is_weakref)
export(is_zap)
export(lang)
export(last_error)
export(last_messages)
export(last_trace)
export(last_warnings)
export(lgl)
export(lgl_along)
export(list2)
export(ll)
export(local_bindings)
export(local_error_call)
export(local_interactive)
export(local_options)
export(local_use_cli)
export(locally)
export(maybe_missing)
export(message_cnd)
export(missing_arg)
export(na_chr)
export(na_cpl)
export(na_dbl)
export(na_int)
export(na_lgl)
export(names2)
export(names_inform_repair)
export(new_box)
export(new_call)
export(new_character)
export(new_complex)
export(new_data_mask)
export(new_double)
export(new_environment)
export(new_formula)
export(new_function)
export(new_integer)
export(new_list)
export(new_logical)
export(new_node)
export(new_quosure)
export(new_quosures)
export(new_raw)
export(new_weakref)
export(node_caar)
export(node_cadr)
export(node_car)
export(node_cdar)
export(node_cddr)
export(node_cdr)
export(node_poke_caar)
export(node_poke_cadr)
export(node_poke_car)
export(node_poke_cdar)
export(node_poke_cddr)
export(node_poke_cdr)
export(node_poke_tag)
export(node_tag)
export(ns_env)
export(ns_env_name)
export(ns_imports_env)
export(obj_address)
export(on_load)
export(on_package_load)
export(pairlist2)
export(parse_bytes)
export(parse_expr)
export(parse_exprs)
export(parse_quo)
export(parse_quos)
export(peek_option)
export(peek_options)
export(pkg_env)
export(pkg_env_name)
export(prim_name)
export(push_options)
export(qq_show)
export(quo)
export(quo_expr)
export(quo_get_env)
export(quo_get_expr)
export(quo_is_call)
export(quo_is_missing)
export(quo_is_null)
export(quo_is_symbol)
export(quo_is_symbolic)
export(quo_label)
export(quo_name)
export(quo_set_env)
export(quo_set_expr)
export(quo_squash)
export(quo_text)
export(quos)
export(quos_auto_name)
export(raw_deparse_str)
export(rep_along)
export(rep_named)
export(return_from)
export(run_on_load)
export(scoped_bindings)
export(scoped_env)
export(scoped_interactive)
export(scoped_options)
export(search_env)
export(search_envs)
export(seq2)
export(seq2_along)
export(set_attrs)
export(set_env)
export(set_expr)
export(set_names)
export(signal)
export(splice)
export(squash)
export(squash_chr)
export(squash_cpl)
export(squash_dbl)
export(squash_if)
export(squash_int)
export(squash_lgl)
export(squash_raw)
export(string)
export(switch_class)
export(switch_type)
export(sym)
export(syms)
export(trace_back)
export(trace_length)
export(try_fetch)
export(type_of)
export(unbox)
export(vec_poke_n)
export(vec_poke_range)
export(warn)
export(warning_cnd)
export(with_bindings)
export(with_env)
export(with_handlers)
export(with_interactive)
export(with_options)
export(wref_key)
export(wref_value)
export(zap)
export(zap_srcref)
importFrom(stats,median)
importFrom(stats,quantile)
importFrom(utils,adist)
importFrom(utils,str)
useDynLib(rlang, .registration = TRUE)
rlang/LICENSE.note 0000644 0001762 0000144 00000003315 14127057575 013345 0 ustar ligges users The implementation of `hash()` uses the xxHash library from Yann Collet, which
is released under the BSD 2-Clause license. This library has been embedded into
rlang, without modification, in `src/internal/xxhash/`. A copy of the
BSD 2-Clause license is provided below.
BSD 2-Clause License -----------------------------------------------------------
xxHash Library
Copyright (c) 2012-2020 Yann Collet
All rights reserved.
BSD 2-Clause License (https://www.opensource.org/licenses/bsd-license.php)
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or
other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
rlang/LICENSE 0000644 0001762 0000144 00000000053 14127057575 012375 0 ustar ligges users YEAR: 2020
COPYRIGHT HOLDER: rlang authors
rlang/README.md 0000644 0001762 0000144 00000006401 14175213516 012642 0 ustar ligges users rlang
=======================================================
[](https://github.com/r-lib/rlang/actions)
[](https://app.codecov.io/gh/r-lib/rlang?branch=main)
[](https://lifecycle.r-lib.org/articles/stages.html)
rlang is a collection of frameworks and APIs for programming with R.
## Frameworks
Two comprehensive frameworks are implemented in rlang.
* __tidy eval__, a programmable [data-masking](https://rlang.r-lib.org/reference/topic-data-mask.html) framework used in tidyverse packages like dplyr and ggplot2. As a user, you will encounter the embracing operator [`{{`](https://rlang.r-lib.org/reference/embrace-operator.html) and name injection with the [glue](https://glue.tidyverse.org/) operators [`"{"`](https://rlang.r-lib.org/reference/glue-operators.html) and [`"{{"`](https://rlang.r-lib.org/reference/glue-operators.html).
* __rlang errors__, a set of tools to signal and display errors. This includes backtrace capture with `global_entrace()` and backtrace display with `last_error()` and `last_warnings()`. Use `abort()` to create errors with bullet lists, structured metadata, and error chaining support.
The display of error messages is optimised for bullet lists and chained errors and optionally integrates with the cli package (see `local_use_cli()`).
## Argument intake
A set of tools help you check, validate, and preprocess arguments.
* Checking function arguments, e.g. `arg_match()`, `check_required()`, and `check_exclusive()`.
* Checking dots, e.g. `check_dots_used()` and `check_dots_empty()`.
* Collecting [dynamic dots](https://rlang.r-lib.org/reference/dyn-dots.html), e.g. `list2()`. These dots support splicing with [`!!!`](https://rlang.r-lib.org/reference/splice-operator.html) and name injection with the [glue](https://glue.tidyverse.org/) operators [`"{"`](https://rlang.r-lib.org/reference/glue-operators.html) and [`"{{"`](https://rlang.r-lib.org/reference/glue-operators.html).
## Programming interfaces
rlang provides various interfaces for working with R and R objects.
* The R session, e.g. `check_installed()`, `on_load()`, and `on_package_load()`.
* Environments, e.g. `env()`, `env_has()`, `env_get()`, `env_bind()`, `env_unbind()`, `env_print()`, and `local_bindings()`.
* Evaluation, e.g. `inject()` and `eval_bare()`.
* Calls and symbols, e.g. `call2()`, `is_call()`, `is_call_simple()`, `data_sym()`, and `data_syms()`.
* Functions, e.g. `new_function()` and `as_function()`. The latter supports the purrr-style formula notation for lambda functions.
## Installation
Install the released version of rlang from CRAN:
```r
install.packages("rlang")
```
Or install the development version from GitHub with:
```r
# install.packages("pak")
pak::pkg_install("r-lib/rlang")
```
## Code of Conduct
Please note that the rlang project is released with a [Contributor Code of Conduct](https://rlang.r-lib.org/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.
rlang/man/ 0000755 0001762 0000144 00000000000 14176531477 012147 5 ustar ligges users rlang/man/prim_name.Rd 0000644 0001762 0000144 00000000516 14127057575 014405 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fn.R
\name{prim_name}
\alias{prim_name}
\title{Name of a primitive function}
\usage{
prim_name(prim)
}
\arguments{
\item{prim}{A primitive function such as \code{\link[base:c]{base::c()}}.}
}
\description{
Name of a primitive function
}
\keyword{internal}
rlang/man/hash.Rd 0000644 0001762 0000144 00000002716 14175213516 013355 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hash.R
\name{hash}
\alias{hash}
\alias{hash_file}
\title{Hashing}
\usage{
hash(x)
hash_file(path)
}
\arguments{
\item{x}{An object.}
\item{path}{A character vector of paths to the files to be hashed.}
}
\value{
\itemize{
\item For \code{hash()}, a single character string containing the hash.
\item For \code{hash_file()}, a character vector containing one hash per file.
}
}
\description{
\itemize{
\item \code{hash()} hashes an arbitrary R object.
\item \code{hash_file()} hashes the data contained in a file.
}
The generated hash is guaranteed to be reproducible across platforms that
have the same endianness and are using the same R version.
}
\details{
These hashers use the XXH128 hash algorithm of the xxHash library, which
generates a 128-bit hash. Both are implemented as streaming hashes, which
generate the hash with minimal extra memory usage.
For \code{hash()}, objects are converted to binary using R's native serialization
tools. On R >= 3.5.0, serialization version 3 is used, otherwise version 2 is
used. See \code{\link[=serialize]{serialize()}} for more information about the serialization version.
}
\examples{
hash(c(1, 2, 3))
hash(mtcars)
authors <- file.path(R.home("doc"), "AUTHORS")
copying <- file.path(R.home("doc"), "COPYING")
hashes <- hash_file(c(authors, copying))
hashes
# If you need a single hash for multiple files,
# hash the result of `hash_file()`
hash(hashes)
}
rlang/man/zap_srcref.Rd 0000644 0001762 0000144 00000001534 14127057575 014575 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/attr.R
\name{zap_srcref}
\alias{zap_srcref}
\title{Zap source references}
\usage{
zap_srcref(x)
}
\arguments{
\item{x}{An R object. Functions and calls are walked recursively.}
}
\description{
There are a number of situations where R creates source references:
\itemize{
\item Reading R code from a file with \code{source()} and \code{parse()} might save
source references inside calls to \code{function} and \verb{\{}.
\item \code{\link[=sys.call]{sys.call()}} includes a source reference if possible.
\item Creating a closure stores the source reference from the call to
\code{function}, if any.
}
These source references take up space and might cause a number of
issues. \code{zap_srcref()} recursively walks through expressions and
functions to remove all source references.
}
rlang/man/scoped_interactive.Rd 0000644 0001762 0000144 00000002745 14175213516 016306 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{scoped_interactive}
\alias{scoped_interactive}
\alias{scoped_options}
\alias{scoped_bindings}
\title{Deprecated \code{scoped_} functions}
\usage{
scoped_interactive(value = TRUE, frame = caller_env())
scoped_options(..., .frame = caller_env())
scoped_bindings(..., .env = .frame, .frame = caller_env())
}
\arguments{
\item{value}{A single \code{TRUE} or \code{FALSE}. This overrides the return
value of \code{is_interactive()}.}
\item{frame}{The environment of a running function which defines
the scope of the temporary options. When the function returns,
the options are reset to their original values.}
\item{...}{For \code{local_options()} and \code{push_options()}, named
values defining new option values. For \code{peek_options()}, strings
or character vectors of option names.}
\item{.frame}{The environment of a running function which defines
the scope of the temporary options. When the function returns,
the options are reset to their original values.}
\item{.env}{An environment.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
Deprecated as of rlang 0.4.2. Use \code{\link[=local_interactive]{local_interactive()}},
\code{\link[=local_options]{local_options()}}, or \code{\link[=local_bindings]{local_bindings()}} instead.
}
\keyword{internal}
rlang/man/env_inherits.Rd 0000644 0001762 0000144 00000000655 14127057575 015137 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env.R
\name{env_inherits}
\alias{env_inherits}
\title{Does environment inherit from another environment?}
\usage{
env_inherits(env, ancestor)
}
\arguments{
\item{env}{An environment.}
\item{ancestor}{Another environment from which \code{x} might inherit.}
}
\description{
This returns \code{TRUE} if \code{x} has \code{ancestor} among its parents.
}
rlang/man/f_text.Rd 0000644 0001762 0000144 00000001320 14127057575 013721 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/formula.R
\name{f_text}
\alias{f_text}
\alias{f_name}
\alias{f_label}
\title{Turn RHS of formula into a string or label}
\usage{
f_text(x, width = 60L, nlines = Inf)
f_name(x)
f_label(x)
}
\arguments{
\item{x}{A formula.}
\item{width}{Width of each line.}
\item{nlines}{Maximum number of lines to extract.}
}
\description{
Equivalent of \code{\link[=expr_text]{expr_text()}} and \code{\link[=expr_label]{expr_label()}} for formulas.
}
\examples{
f <- ~ a + b + bc
f_text(f)
f_label(f)
# Names a quoted with ``
f_label(~ x)
# Strings are encoded
f_label(~ "a\nb")
# Long expressions are collapsed
f_label(~ foo({
1 + 2
print(x)
}))
}
rlang/man/env_binding_lock.Rd 0000644 0001762 0000144 00000003204 14175213516 015715 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-binding.R
\name{env_binding_lock}
\alias{env_binding_lock}
\alias{env_binding_unlock}
\alias{env_binding_are_locked}
\title{Lock or unlock environment bindings}
\usage{
env_binding_lock(env, nms = NULL)
env_binding_unlock(env, nms = NULL)
env_binding_are_locked(env, nms = NULL)
}
\arguments{
\item{env}{An environment.}
\item{nms}{Names of bindings. Defaults to all bindings in \code{env}.}
}
\value{
\code{env_binding_are_unlocked()} returns a logical vector as
long as \code{nms} and named after it. \code{env_binding_lock()} and
\code{env_binding_unlock()} return the old value of
\code{env_binding_are_unlocked()} invisibly.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
Locked environment bindings trigger an error when an attempt is
made to redefine the binding.
}
\examples{
# Bindings are unlocked by default:
env <- env(a = "A", b = "B")
env_binding_are_locked(env)
# But can optionally be locked:
env_binding_lock(env, "a")
env_binding_are_locked(env)
# If run, the following would now return an error because `a` is locked:
# env_bind(env, a = "foo")
# with_env(env, a <- "bar")
# Let's unlock it. Note that the return value indicate which
# bindings were locked:
were_locked <- env_binding_unlock(env)
were_locked
# Now that it is unlocked we can modify it again:
env_bind(env, a = "foo")
with_env(env, a <- "bar")
env$a
}
\seealso{
\code{\link[=env_lock]{env_lock()}} for locking an environment.
}
\keyword{internal}
rlang/man/stack-deprecated.Rd 0000644 0001762 0000144 00000001071 14175213516 015626 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{stack-deprecated}
\alias{stack-deprecated}
\alias{ctxt_frame}
\alias{global_frame}
\title{Call stack information}
\usage{
ctxt_frame(n = 1)
global_frame()
}
\arguments{
\item{n}{The number of frames to go back in the stack.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
Deprecated as of rlang 0.3.0.
}
\keyword{internal}
rlang/man/env_name.Rd 0000644 0001762 0000144 00000002374 14127057575 014232 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-special.R
\name{env_name}
\alias{env_name}
\alias{env_label}
\title{Label of an environment}
\usage{
env_name(env)
env_label(env)
}
\arguments{
\item{env}{An environment.}
}
\description{
Special environments like the global environment have their own
names. \code{env_name()} returns:
\itemize{
\item "global" for the global environment.
\item "empty" for the empty environment.
\item "base" for the base package environment (the last environment on
the search path).
\item "namespace:pkg" if \code{env} is the namespace of the package "pkg".
\item The \code{name} attribute of \code{env} if it exists. This is how the
\link[=search_envs]{package environments} and the \link[=ns_imports_env]{imports environments} store their names. The name of package
environments is typically "package:pkg".
\item The empty string \code{""} otherwise.
}
\code{env_label()} is exactly like \code{env_name()} but returns the memory
address of anonymous environments as fallback.
}
\examples{
# Some environments have specific names:
env_name(global_env())
env_name(ns_env("rlang"))
# Anonymous environments don't have names but are labelled by their
# address in memory:
env_name(env())
env_label(env())
}
rlang/man/stack.Rd 0000644 0001762 0000144 00000002770 14175213516 013537 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stack.R
\name{stack}
\alias{stack}
\alias{current_call}
\alias{current_fn}
\alias{current_env}
\alias{caller_call}
\alias{caller_fn}
\alias{caller_env}
\alias{frame_call}
\alias{frame_fn}
\title{Get properties of the current or caller frame}
\usage{
current_call()
current_fn()
current_env()
caller_call(n = 1)
caller_fn(n = 1)
caller_env(n = 1)
frame_call(frame = caller_env())
frame_fn(frame = caller_env())
}
\arguments{
\item{n}{The number of callers to go back.}
\item{frame}{A frame environment of a currently running function,
as returned by \code{\link[=caller_env]{caller_env()}}. \code{NULL} is returned if the
environment does not exist on the stack.}
}
\description{
These accessors retrieve properties of frames on the call stack.
The prefix indicates for which frame a property should be accessed:
\itemize{
\item From the current frame with \code{current_} accessors.
\item From a calling frame with \code{caller_} accessors.
\item From a matching frame with \code{frame_} accessors.
}
The suffix indicates which property to retrieve:
\itemize{
\item \verb{_fn} accessors return the function running in the frame.
\item \verb{_call} accessors return the defused call with which the function
running in the frame was invoked.
\item \verb{_env} accessors return the execution environment of the function
running in the frame.
}
}
\seealso{
\code{\link[=caller_env]{caller_env()}} and \code{\link[=current_env]{current_env()}}
}
rlang/man/defusing-advanced.Rd 0000644 0001762 0000144 00000014011 14175213516 015770 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nse-defuse.R
\name{defusing-advanced}
\alias{defusing-advanced}
\alias{enexpr}
\alias{exprs}
\alias{enexprs}
\alias{ensym}
\alias{ensyms}
\alias{quo}
\alias{quos}
\alias{enquo0}
\alias{enquos0}
\title{Advanced defusal operators}
\usage{
enexpr(arg)
exprs(
...,
.named = FALSE,
.ignore_empty = c("trailing", "none", "all"),
.unquote_names = TRUE
)
enexprs(
...,
.named = FALSE,
.ignore_empty = c("trailing", "none", "all"),
.unquote_names = TRUE,
.homonyms = c("keep", "first", "last", "error"),
.check_assign = FALSE
)
ensym(arg)
ensyms(
...,
.named = FALSE,
.ignore_empty = c("trailing", "none", "all"),
.unquote_names = TRUE,
.homonyms = c("keep", "first", "last", "error"),
.check_assign = FALSE
)
quo(expr)
quos(
...,
.named = FALSE,
.ignore_empty = c("trailing", "none", "all"),
.unquote_names = TRUE
)
enquo0(arg)
enquos0(...)
}
\arguments{
\item{arg}{An unquoted argument name. The expression
supplied to that argument is defused and returned.}
\item{...}{For \code{enexprs()}, \code{ensyms()} and \code{enquos()}, names of
arguments to defuse. For \code{exprs()} and \code{quos()}, expressions
to defuse.}
\item{.named}{If \code{TRUE}, unnamed inputs are automatically named
with \code{\link[=as_label]{as_label()}}. This is equivalent to applying
\code{\link[=exprs_auto_name]{exprs_auto_name()}} on the result. If \code{FALSE}, unnamed elements
are left as is and, if fully unnamed, the list is given minimal
names (a vector of \code{""}). If \code{NULL}, fully unnamed results are
left with \code{NULL} names.}
\item{.ignore_empty}{Whether to ignore empty arguments. Can be one
of \code{"trailing"}, \code{"none"}, \code{"all"}. If \code{"trailing"}, only the
last argument is ignored if it is empty. Named arguments are not
considered empty.}
\item{.unquote_names}{Whether to treat \verb{:=} as \code{=}. Unlike \code{=}, the
\verb{:=} syntax supports \link[=glue-operators]{names injection}.}
\item{.homonyms}{How to treat arguments with the same name. The
default, \code{"keep"}, preserves these arguments. Set \code{.homonyms} to
\code{"first"} to only keep the first occurrences, to \code{"last"} to keep
the last occurrences, and to \code{"error"} to raise an informative
error and indicate what arguments have duplicated names.}
\item{.check_assign}{Whether to check for \verb{<-} calls. When \code{TRUE} a
warning recommends users to use \code{=} if they meant to match a
function parameter or wrap the \verb{<-} call in curly braces otherwise.
This ensures assignments are explicit.}
\item{expr}{An expression to defuse.}
}
\description{
These advanced operators \link[=topic-defuse]{defuse} R expressions.
\code{\link[=expr]{expr()}}, \code{\link[=enquo]{enquo()}}, and \code{\link[=enquos]{enquos()}} are sufficient for most
purposes but rlang provides these other operations, either for
completeness or because they are useful to experts.
\itemize{
\item \code{exprs()} is the plural variant of \code{expr()}. It returns a list of
expressions. It is like \code{\link[base:list]{base::alist()}} but with
\link[=nse-inject]{injection} support.
\item \code{quo()} and \code{quos()} are like \code{expr()} and \code{exprs()} but return
quosures instead of naked expressions. When you are defusing
your own local expressions (by opposition to function arguments
where non-local expressions are supplied by your users), there
is generally no need to attach the current environment in a
quosure. See \ifelse{html}{\link[=topic-quosure]{What are quosures and when are they needed?}}{\link[=topic-quosure]{What are quosures and when are they needed?}}.
\item \code{enexpr()} and \code{enexprs()} are like \code{\link[=enquo]{enquo()}} and \code{\link[=enquos]{enquos()}} but
return naked expressions instead of quosures. These operators
should very rarely be used because they lose track of the
environment of defused arguments.
\item \code{ensym()} and \code{ensyms()} are like \code{enexpr()} and \code{enexprs()} but
they throw an error when the defused expressions are not simple
symbols. They also support strings which are interpreted as
symbols. These functions are modelled on the behaviour of the
left-hand side of \code{=} and \verb{<-} where you can supply symbols and
strings interchangeably.\preformatted{"foo" <- NULL
list("foo" = NULL)
}
\item \code{enquo0} and \code{enquos0()} are like \code{enquo()} and \code{enquos()} but
without injection support. The injection operators \verb{!!}, \verb{!!!},
and \verb{\{\{} are not processed, instead they are preserved in the
defused expression. This makes it possible to defuse
expressions that potentially contain injection operators meant
for later use. The trade off is that it makes it harder for
users to inject expressions in your function. They have to
enable injection explicitly with \code{\link[=inject]{inject()}}.
None of the features of \link[=dyn-dots]{dynamic dots} are available
when defusing with \code{enquos0()}. For instance, trailing empty
arguments are not automatically trimmed.
}
}
\examples{
# `exprs()` is the plural variant of `expr()`
exprs(foo, bar, bar)
# `quo()` and `quos()` are the quosure variants of `expr()` and `exprs()`
quo(foo)
quos(foo, bar)
# `enexpr()` and `enexprs()` are the naked variants of `enquo()` and `enquos()`
my_function1 <- function(arg) enexpr(arg)
my_function2 <- function(arg, ...) enexprs(arg, ...)
my_function1(1 + 1)
my_function2(1 + 1, 10 * 2)
# `ensym()` and `ensyms()` are symbol variants of `enexpr()` and `enexprs()`
my_function3 <- function(arg) ensym(arg)
my_function4 <- function(arg, ...) ensyms(arg, ...)
# The user must supply symbols
my_function3(foo)
my_function4(foo, bar)
# Complex expressions are an error
try(my_function3(1 + 1))
try(my_function4(1 + 1, 10 * 2))
# `enquo0()` and `enquos0()` disable injection operators
automatic_injection <- function(x) enquo(x)
no_injection <- function(x) enquo0(x)
automatic_injection(foo(!!!1:3))
no_injection(foo(!!!1:3))
# Injection can still be done explicitly
inject(no_injection(foo(!!!1:3)))
}
\keyword{internal}
rlang/man/env_bind.Rd 0000644 0001762 0000144 00000013520 14175213516 014211 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-binding.R
\name{env_bind}
\alias{env_bind}
\alias{env_bind_lazy}
\alias{env_bind_active}
\alias{\%<~\%}
\title{Bind symbols to objects in an environment}
\usage{
env_bind(.env, ...)
env_bind_lazy(.env, ..., .eval_env = caller_env())
env_bind_active(.env, ...)
lhs \%<~\% rhs
}
\arguments{
\item{.env}{An environment.}
\item{...}{<\link[=dyn-dots]{dynamic}> Named objects (\code{env_bind()}),
expressions \code{env_bind_lazy()}, or functions (\code{env_bind_active()}).
Use \code{\link[=zap]{zap()}} to remove bindings.}
\item{.eval_env}{The environment where the expressions will be
evaluated when the symbols are forced.}
\item{lhs}{The variable name to which \code{rhs} will be lazily assigned.}
\item{rhs}{An expression lazily evaluated and assigned to \code{lhs}.}
}
\value{
The input object \code{.env}, with its associated environment
modified in place, invisibly.
}
\description{
These functions create bindings in an environment. The bindings are
supplied through \code{...} as pairs of names and values or expressions.
\code{env_bind()} is equivalent to evaluating a \verb{<-} expression within
the given environment. This function should take care of the
majority of use cases but the other variants can be useful for
specific problems.
\itemize{
\item \code{env_bind()} takes named \emph{values} which are bound in \code{.env}.
\code{env_bind()} is equivalent to \code{\link[base:assign]{base::assign()}}.
\item \code{env_bind_active()} takes named \emph{functions} and creates active
bindings in \code{.env}. This is equivalent to
\code{\link[base:bindenv]{base::makeActiveBinding()}}. An active binding executes a
function each time it is evaluated. The arguments are passed to
\code{\link[=as_function]{as_function()}} so you can supply formulas instead of functions.
Remember that functions are scoped in their own environment.
These functions can thus refer to symbols from this enclosure
that are not actually in scope in the dynamic environment where
the active bindings are invoked. This allows creative solutions
to difficult problems (see the implementations of \code{dplyr::do()}
methods for an example).
\item \code{env_bind_lazy()} takes named \emph{expressions}. This is equivalent
to \code{\link[base:delayedAssign]{base::delayedAssign()}}. The arguments are captured with
\code{\link[=exprs]{exprs()}} (and thus support call-splicing and unquoting) and
assigned to symbols in \code{.env}. These expressions are not
evaluated immediately but lazily. Once a symbol is evaluated, the
corresponding expression is evaluated in turn and its value is
bound to the symbol (the expressions are thus evaluated only
once, if at all).
\item \verb{\%<~\%} is a shortcut for \code{env_bind_lazy()}. It works like \verb{<-}
but the RHS is evaluated lazily.
}
}
\section{Side effects}{
Since environments have reference semantics (see relevant section
in \code{\link[=env]{env()}} documentation), modifying the bindings of an environment
produces effects in all other references to that environment. In
other words, \code{env_bind()} and its variants have side effects.
Like other side-effecty functions like \code{par()} and \code{options()},
\code{env_bind()} and variants return the old values invisibly.
}
\examples{
# env_bind() is a programmatic way of assigning values to symbols
# with `<-`. We can add bindings in the current environment:
env_bind(current_env(), foo = "bar")
foo
# Or modify those bindings:
bar <- "bar"
env_bind(current_env(), bar = "BAR")
bar
# You can remove bindings by supplying zap sentinels:
env_bind(current_env(), foo = zap())
try(foo)
# Unquote-splice a named list of zaps
zaps <- rep_named(c("foo", "bar"), list(zap()))
env_bind(current_env(), !!!zaps)
try(bar)
# It is most useful to change other environments:
my_env <- env()
env_bind(my_env, foo = "foo")
my_env$foo
# A useful feature is to splice lists of named values:
vals <- list(a = 10, b = 20)
env_bind(my_env, !!!vals, c = 30)
my_env$b
my_env$c
# You can also unquote a variable referring to a symbol or a string
# as binding name:
var <- "baz"
env_bind(my_env, !!var := "BAZ")
my_env$baz
# The old values of the bindings are returned invisibly:
old <- env_bind(my_env, a = 1, b = 2, baz = "baz")
old
# You can restore the original environment state by supplying the
# old values back:
env_bind(my_env, !!!old)
# env_bind_lazy() assigns expressions lazily:
env <- env()
env_bind_lazy(env, name = { cat("forced!\n"); "value" })
# Referring to the binding will cause evaluation:
env$name
# But only once, subsequent references yield the final value:
env$name
# You can unquote expressions:
expr <- quote(message("forced!"))
env_bind_lazy(env, name = !!expr)
env$name
# By default the expressions are evaluated in the current
# environment. For instance we can create a local binding and refer
# to it, even though the variable is bound in a different
# environment:
who <- "mickey"
env_bind_lazy(env, name = paste(who, "mouse"))
env$name
# You can specify another evaluation environment with `.eval_env`:
eval_env <- env(who = "minnie")
env_bind_lazy(env, name = paste(who, "mouse"), .eval_env = eval_env)
env$name
# Or by unquoting a quosure:
quo <- local({
who <- "fievel"
quo(paste(who, "mouse"))
})
env_bind_lazy(env, name = !!quo)
env$name
# You can create active bindings with env_bind_active(). Active
# bindings execute a function each time they are evaluated:
fn <- function() {
cat("I have been called\n")
rnorm(1)
}
env <- env()
env_bind_active(env, symbol = fn)
# `fn` is executed each time `symbol` is evaluated or retrieved:
env$symbol
env$symbol
eval_bare(quote(symbol), env)
eval_bare(quote(symbol), env)
# All arguments are passed to as_function() so you can use the
# formula shortcut:
env_bind_active(env, foo = ~ runif(1))
env$foo
env$foo
}
\seealso{
\code{\link[=env_poke]{env_poke()}} for binding a single element.
}
rlang/man/call_modify.Rd 0000644 0001762 0000144 00000005632 14175213516 014714 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/call.R
\name{call_modify}
\alias{call_modify}
\title{Modify the arguments of a call}
\usage{
call_modify(
.call,
...,
.homonyms = c("keep", "first", "last", "error"),
.standardise = NULL,
.env = caller_env()
)
}
\arguments{
\item{.call}{Can be a call, a formula quoting a call in the
right-hand side, or a frame object from which to extract the call
expression.}
\item{...}{<\link[=dyn-dots]{dynamic}> Named or unnamed expressions
(constants, names or calls) used to modify the call. Use \code{\link[=zap]{zap()}}
to remove arguments. Empty arguments are preserved.}
\item{.homonyms}{How to treat arguments with the same name. The
default, \code{"keep"}, preserves these arguments. Set \code{.homonyms} to
\code{"first"} to only keep the first occurrences, to \code{"last"} to keep
the last occurrences, and to \code{"error"} to raise an informative
error and indicate what arguments have duplicated names.}
\item{.standardise, .env}{Deprecated as of rlang 0.3.0. Please
call \code{\link[=call_match]{call_match()}} manually.}
}
\value{
A quosure if \code{.call} is a quosure, a call otherwise.
}
\description{
If you are working with a user-supplied call, make sure the
arguments are standardised with \code{\link[=call_match]{call_match()}} before
modifying the call.
}
\examples{
call <- quote(mean(x, na.rm = TRUE))
# Modify an existing argument
call_modify(call, na.rm = FALSE)
call_modify(call, x = quote(y))
# Remove an argument
call_modify(call, na.rm = zap())
# Add a new argument
call_modify(call, trim = 0.1)
# Add an explicit missing argument:
call_modify(call, na.rm = )
# Supply a list of new arguments with `!!!`
newargs <- list(na.rm = NULL, trim = 0.1)
call <- call_modify(call, !!!newargs)
call
# Remove multiple arguments by splicing zaps:
newargs <- rep_named(c("na.rm", "trim"), list(zap()))
call <- call_modify(call, !!!newargs)
call
# Modify the `...` arguments as if it were a named argument:
call <- call_modify(call, ... = )
call
call <- call_modify(call, ... = zap())
call
# When you're working with a user-supplied call, standardise it
# beforehand in case it includes unmatched arguments:
user_call <- quote(matrix(x, nc = 3))
call_modify(user_call, ncol = 1)
# `call_match()` applies R's argument matching rules. Matching
# ensures you're modifying the intended argument.
user_call <- call_match(user_call, matrix)
user_call
call_modify(user_call, ncol = 1)
# By default, arguments with the same name are kept. This has
# subtle implications, for instance you can move an argument to
# last position by removing it and remapping it:
call <- quote(foo(bar = , baz))
call_modify(call, bar = NULL, bar = missing_arg())
# You can also choose to keep only the first or last homonym
# arguments:
args <- list(bar = NULL, bar = missing_arg())
call_modify(call, !!!args, .homonyms = "first")
call_modify(call, !!!args, .homonyms = "last")
}
rlang/man/zap.Rd 0000644 0001762 0000144 00000001522 14127057575 013226 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/s3.R
\name{zap}
\alias{zap}
\alias{is_zap}
\title{Create zap objects}
\usage{
zap()
is_zap(x)
}
\arguments{
\item{x}{An object to test.}
}
\description{
\code{zap()} creates a sentinel object that indicates that an object
should be removed. For instance, named zaps instruct \code{\link[=env_bind]{env_bind()}}
and \code{\link[=call_modify]{call_modify()}} to remove those objects from the environment or
the call.
The advantage of zap objects is that they unambiguously signal the
intent of removing an object. Sentinels like \code{NULL} or
\code{\link[=missing_arg]{missing_arg()}} are ambiguous because they represent valid R
objects.
}
\examples{
# Create one zap object:
zap()
# Create a list of zaps:
rep(list(zap()), 3)
rep_named(c("foo", "bar"), list(zap()))
}
rlang/man/is_condition.Rd 0000644 0001762 0000144 00000000575 14175213516 015114 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd.R
\name{is_condition}
\alias{is_condition}
\alias{is_error}
\alias{is_warning}
\alias{is_message}
\title{Is object a condition?}
\usage{
is_condition(x)
is_error(x)
is_warning(x)
is_message(x)
}
\arguments{
\item{x}{An object to test.}
}
\description{
Is object a condition?
}
\keyword{internal}
rlang/man/scoped_env.Rd 0000644 0001762 0000144 00000001322 14175213516 014547 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{scoped_env}
\alias{scoped_env}
\alias{is_scoped}
\title{Deprecated \code{scoped} functions}
\usage{
scoped_env(nm)
is_scoped(nm)
}
\arguments{
\item{nm}{The name of an environment attached to the search
path. Call \code{\link[base:search]{base::search()}} to see what is currently on the path.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
These functions are deprecated as of rlang 0.3.0. Please use
\code{\link[=is_attached]{is_attached()}} instead.
}
\keyword{internal}
rlang/man/cnd_message.Rd 0000644 0001762 0000144 00000006022 14175213516 014674 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-message.R
\name{cnd_message}
\alias{cnd_message}
\alias{cnd_header}
\alias{cnd_body}
\alias{cnd_footer}
\title{Build an error message from parts}
\usage{
cnd_message(cnd, ..., inherit = TRUE, prefix = FALSE)
cnd_header(cnd, ...)
cnd_body(cnd, ...)
cnd_footer(cnd, ...)
}
\arguments{
\item{cnd}{A condition object.}
\item{...}{Arguments passed to methods.}
\item{inherit}{Wether to include parent messages. Parent messages
are printed with a "Caused by error:" prefix, even if \code{prefix} is
\code{FALSE}.}
\item{prefix}{Whether to print the full message, including the
condition prefix (\verb{Error:}, \verb{Warning:}, \verb{Message:}, or
\verb{Condition:}). The prefix mentions the \code{call} field if present,
and the \code{srcref} info if present. If \code{cnd} has a \code{parent} field
(i.e. the condition is chained), the parent messages are included
in the message with a \verb{Caused by} prefix.}
}
\description{
\code{cnd_message()} assembles an error message from three generics:
\itemize{
\item \code{cnd_header()}
\item \code{cnd_body()}
\item \code{cnd_footer()}
}
Methods for these generics must return a character vector. The
elements are combined into a single string with a newline
separator. Bullets syntax is supported, either through rlang (see
\code{\link[=format_error_bullets]{format_error_bullets()}}), or through cli if the condition has
\code{use_cli_format} set to \code{TRUE}.
The default method for the error header returns the \code{message} field
of the condition object. The default methods for the body and
footer return the the \code{body} and \code{footer} fields if any, or empty
character vectors otherwise.
\code{cnd_message()} is automatically called by the \code{conditionMessage()}
for rlang errors, warnings, and messages. Error classes created
with \code{\link[=abort]{abort()}} only need to implement header, body or footer
methods. This provides a lot of flexibility for hierarchies of
error classes, for instance you could inherit the body of an error
message from a parent class while overriding the header and footer.
}
\section{Overriding header, body, and footer methods}{
Sometimes the contents of an error message depends on the state of
your checking routine. In that case, it can be tricky to lazily
generate error messages with \code{cnd_header()}, \code{cnd_body()}, and
\code{cnd_footer()}: you have the choice between overspecifying your
error class hierarchies with one class per state, or replicating
the type-checking control flow within the \code{cnd_body()} method. None
of these options are ideal.
A better option is to define \code{header}, \code{body}, or \code{footer} fields
in your condition object. These can be a static string, a
\link[=as_function]{lambda-formula}, or a function with the same
signature as \code{cnd_header()}, \code{cnd_body()}, or \code{cnd_footer()}. These
fields override the message generics and make it easy to generate
an error message tailored to the state in which the error was
constructed.
}
rlang/man/topic-multiple-columns.Rd 0000644 0001762 0000144 00000014375 14175213516 017063 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/topic-nse.R
\name{topic-multiple-columns}
\alias{topic-multiple-columns}
\title{Taking multiple columns without \code{...}}
\description{
In this guide we compare ways of taking multiple columns in a single function argument.
As a refresher (see the \link[=topic-data-mask-programming]{programming patterns} article), there are two common ways of passing arguments to \link[=topic-data-mask]{data-masking} functions. For single arguments, embrace with \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}}:\if{html}{\out{
}}\preformatted{my_group_by <- function(data, var) \{
data \%>\% dplyr::group_by(\{\{ var \}\})
\}
my_pivot_longer <- function(data, var) \{
data \%>\% tidyr::pivot_longer(\{\{ var \}\})
\}
}\if{html}{\out{
}}
For multiple arguments in \code{...}, pass them on to functions that also take \code{...} like \code{group_by()}, or pass them within \code{c()} for functions taking tidy selection in a single argument like \code{pivot_longer()}:\if{html}{\out{
}}
But what if you want to take multiple columns in a single named argument rather than in \code{...}?
}
\section{Using tidy selections}{
The idiomatic tidyverse way of taking multiple columns in a single argument is to take a \emph{tidy selection} (see the \link[=topic-data-mask-programming]{Argument behaviours} section). In tidy selections, the syntax for passing multiple columns in a single argument is \code{c()}:\if{html}{\out{
}}
Since \verb{\{\{} inherits behaviour, this implementation of \code{my_pivot_longer()} automatically allows multiple columns passing:\if{html}{\out{
}}\preformatted{my_pivot_longer <- function(data, var) \{
data \%>\% tidyr::pivot_longer(\{\{ var \}\})
\}
mtcars \%>\% my_pivot_longer(c(am, cyl, vs))
}\if{html}{\out{
}}
For \code{group_by()}, which takes data-masked arguments, we'll use \code{across()} as a \emph{bridge} (see \link[=topic-data-mask-programming]{Bridge patterns}).\if{html}{\out{
}}\preformatted{my_group_by <- function(data, var) \{
data \%>\% dplyr::group_by(across(\{\{ var \}\}))
\}
mtcars \%>\% my_group_by(c(am, cyl, vs))
}\if{html}{\out{
}}
When embracing in tidyselect context or using \code{across()} is not possible, you might have to implement tidyselect behaviour manually with \code{tidyselect::eval_select()}.
}
\section{Using external defusal}{
To implement an argument with tidyselect behaviour, it is necessary to \link[=topic-defuse]{defuse} the argument. However defusing an argument which had historically behaved like a regular argument is a rather disruptive breaking change. This is why we could not implement tidy selections in ggplot2 facetting functions like \code{facet_grid()} and \code{facet_wrap()}.
An alternative is to use external defusal of arguments. This is what formula interfaces do for instance. A modelling function takes a formula in a regular argument and the formula defuses the user code:\if{html}{\out{
}}
Once created, the defused expressions contained in the formula are passed around like a normal argument. A similar approach was taken to update \code{facet_} functions to tidy eval. The \code{vars()} function (a simple alias to \code{\link[=quos]{quos()}}) is provided so that users can defuse their arguments externally.\if{html}{\out{
}}
You can implement this approach by simply taking a list of defused expressions as argument. This list can be passed the usual way to other functions taking such lists:\if{html}{\out{
}}
}
\section{A non-approach: Parsing lists}{
Intuitively, many programmers who want to take a list of expressions in a single argument try to defuse an argument and parse it. The user is expected to supply multiple arguments within a \code{list()} expression. When such a call is detected, the arguments are retrieved and spliced with \verb{!!!}. Otherwise, the user is assumed to have supplied a single argument which is injected with \verb{!!}. An implementation along these lines might look like this:\if{html}{\out{
}}\preformatted{my_group_by <- function(data, vars) \{
vars <- enquo(vars)
if (quo_is_call(vars, "list")) \{
expr <- quo_get_expr(vars)
env <- quo_get_env(vars)
args <- as_quosures(call_args(expr), env = env)
data \%>\% dplyr::group_by(!!!args)
\} else \{
data \%>\% dplyr::group_by(!!vars)
\}
\}
}\if{html}{\out{
}}
However this parsing approach quickly shows limits:\if{html}{\out{
}}\preformatted{mtcars \%>\% my_group_by(list2(cyl, am))
#> Error in `group_by()`: Can't add columns.
#> ℹ `..1 = list2(cyl, am)`.
#> ℹ `..1` must be size 32 or 1, not 2.
}\if{html}{\out{
}}
Also, it would be better for overall consistency of interfaces to use the tidyselect syntax \code{c()} for passing multiple columns. In general, we recommend to use either the tidyselect or the external defusal approaches.
}
\keyword{internal}
rlang/man/format_error_call.Rd 0000644 0001762 0000144 00000003404 14175213516 016121 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-abort.R
\name{format_error_call}
\alias{format_error_call}
\title{Validate and format a function call for use in error messages}
\usage{
format_error_call(call)
}
\arguments{
\item{call}{The execution environment of a currently
running function, e.g. \code{caller_env()}. The function will be
mentioned in error messages as the source of the error. See the
\code{call} argument of \code{\link[=abort]{abort()}} for more information.}
}
\value{
Either a string formatted as code or \code{NULL} if a simple
call could not be generated.
}
\description{
\code{format_error_call()} simplifies its input to a simple call (see
section below) and formats the result as code (using cli if
available). Use this function to generate the "in" part
of an error message from a stack frame call.
If passed an environment, the corresponding \code{sys.call()} is taken
as call, unless there is a local flag (see \code{\link[=local_error_call]{local_error_call()}}).
}
\section{Details of formatting}{
\itemize{
\item The arguments of function calls are stripped.
\item Complex function calls containing inlined objects return
\code{NULL}.
\item Calls to \code{if} preserve the condition since it might be
informative. Branches are dropped.
\item Calls to operators and other special syntax are formatted using
their names rather than the potentially confusing function form.
}
}
\examples{
# Arguments are stripped
writeLines(format_error_call(quote(foo(bar, baz))))
# Returns `NULL` with complex calls such as those that contain
# inlined functions
format_error_call(call2(list))
# Operators are formatted using their names rather than in
# function call form
writeLines(format_error_call(quote(1 + 2)))
}
\keyword{internal}
rlang/man/injection-operator.Rd 0000644 0001762 0000144 00000011375 14175213516 016246 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nse-inject.R
\name{injection-operator}
\alias{injection-operator}
\alias{bang-bang}
\alias{!!}
\title{Injection operator \verb{!!}}
\description{
The \link[=topic-inject]{injection} operator \verb{!!} injects a value or
expression inside another expression. In other words, it modifies a
piece of code before R evaluates it.
There are two main cases for injection. You can inject constant
values to work around issues of \link[=topic-data-mask-ambiguity]{scoping ambiguity}, and you can inject \link[=topic-defuse]{defused expressions} like \link[=sym]{symbolised} column names.
}
\section{Where does \verb{!!} work?}{
\verb{!!} does not work everywhere, you can only use it within certain
special functions:
\itemize{
\item Functions taking \link[=topic-defuse]{defused} and
\link[=topic-data-mask]{data-masked} arguments.
Technically, this means function arguments defused with
\ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}} or \code{en}-prefixed operators like
\code{\link[=enquo]{enquo()}}, \code{\link[=enexpr]{enexpr()}}, etc.
\item Inside \code{\link[=inject]{inject()}}.
}
All data-masking verbs in the tidyverse support injection operators
out of the box. With base functions, you need to use \code{\link[=inject]{inject()}} to
enable \verb{!!}. Using \verb{!!} out of context may lead to incorrect
results, see \ifelse{html}{\link[=topic-inject-out-of-context]{What happens if I use injection operators out of context?}}{\link[=topic-inject-out-of-context]{What happens if I use injection operators out of context?}}.
The examples below are built around the base function \code{\link[=with]{with()}}.
Since it's not a tidyverse function we will use \code{\link[=inject]{inject()}} to enable
\verb{!!} usage.
}
\section{Injecting values}{
Data-masking functions like \code{\link[=with]{with()}} are handy because you can
refer to column names in your computations. This comes at the price
of data mask ambiguity: if you have defined an env-variable of the
same name as a data-variable, you get a name collisions. This
collision is always resolved by giving precedence to the
data-variable (it masks the env-variable):\if{html}{\out{
}}
Note that the \code{\link{.env}} pronoun is a simpler way of solving the
ambiguity. See \ifelse{html}{\link[=topic-data-mask-ambiguity]{The data mask ambiguity}}{\link[=topic-data-mask-ambiguity]{The data mask ambiguity}} for more about
this.
}
\section{Injecting expressions}{
Injection is also useful for modifying parts of a \link[=topic-defuse]{defused expression}. In the following example we use the
\link[=topic-metaprogramming]{symbolise-and-inject pattern} to
inject a column name inside a data-masked expression.\if{html}{\out{
}}
Since \code{\link[=with]{with()}} is a base function, you can't inject
\link[=topic-quosure]{quosures}, only naked symbols and calls. This
isn't a problem here because we're injecting the name of a data
frame column. If the environment is important, try injecting a
pre-computed value instead.
}
\section{When do I need \verb{!!}?}{
With tidyverse APIs, injecting expressions with \verb{!!} is no longer a
common pattern. First, the \code{\link{.env}} pronoun solves the
ambiguity problem in a more intuitive way:\if{html}{\out{
}}
Second, the embrace operator \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}} makes the
\link[=topic-metaprogramming]{defuse-and-inject pattern} easier to
learn and use.\if{html}{\out{
}}\preformatted{my_mean <- function(data, var) \{
data \%>\% dplyr::summarise(mean(\{\{ var \}\}))
\}
# Equivalent to
my_mean <- function(data, var) \{
data \%>\% dplyr::summarise(mean(!!enquo(var)))
\}
}\if{html}{\out{
}}
\verb{!!} is a good tool to learn for advanced applications but our
hope is that it isn't needed for common data analysis cases.
}
\seealso{
\itemize{
\item \ifelse{html}{\link[=topic-inject]{Injecting with !!, !!!, and glue syntax}}{\link[=topic-inject]{Injecting with !!, !!!, and glue syntax}}
\item \ifelse{html}{\link[=topic-metaprogramming]{Metaprogramming patterns}}{\link[=topic-metaprogramming]{Metaprogramming patterns}}
}
}
rlang/man/f_rhs.Rd 0000644 0001762 0000144 00000001543 13351410454 013523 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/formula.R
\name{f_rhs}
\alias{f_rhs}
\alias{f_rhs<-}
\alias{f_lhs}
\alias{f_lhs<-}
\alias{f_env}
\alias{f_env<-}
\title{Get or set formula components}
\usage{
f_rhs(f)
f_rhs(x) <- value
f_lhs(f)
f_lhs(x) <- value
f_env(f)
f_env(x) <- value
}
\arguments{
\item{f, x}{A formula}
\item{value}{The value to replace with.}
}
\value{
\code{f_rhs} and \code{f_lhs} return language objects (i.e. atomic
vectors of length 1, a name, or a call). \code{f_env} returns an
environment.
}
\description{
\code{f_rhs} extracts the righthand side, \code{f_lhs} extracts the lefthand
side, and \code{f_env} extracts the environment. All functions throw an
error if \code{f} is not a formula.
}
\examples{
f_rhs(~ 1 + 2 + 3)
f_rhs(~ x)
f_rhs(~ "A")
f_rhs(1 ~ 2)
f_lhs(~ y)
f_lhs(x ~ y)
f_env(~ x)
}
rlang/man/local_use_cli.Rd 0000644 0001762 0000144 00000004054 14175213516 015224 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-abort.R
\name{local_use_cli}
\alias{local_use_cli}
\title{Use cli to format error messages}
\usage{
local_use_cli(..., format = TRUE, inline = FALSE, frame = caller_env())
}
\arguments{
\item{...}{These dots are for future extensions and must be empty.}
\item{format}{Whether to use cli at print-time to format messages
and bullets.}
\item{inline}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} Whether to use
cli at throw-time to format the inline parts of a message. This
makes it possible to use cli interpolation and formatting with
\code{abort()}.}
\item{frame}{A package namespace or an environment of a running
function.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
\code{local_use_cli()} marks a package namespace or the environment of a
running function with a special flag that instructs \code{\link[=abort]{abort()}} to
use cli to format error messages. This formatting happens lazily,
at print-time, in various places:
\itemize{
\item When an unexpected error is displayed to the user.
\item When a captured error is printed in the console, for instance via
\code{\link[=last_error]{last_error()}}.
\item When \code{\link[=conditionMessage]{conditionMessage()}} is called.
}
cli formats messages and bullets with indentation and
width-wrapping to produce a polished display of messages.
}
\section{Usage}{
To use cli formatting automatically in your package:
\enumerate{
\item Make sure \code{\link[=run_on_load]{run_on_load()}} is called from your \code{.onLoad()} hook.
\item Call \code{on_load(local_use_cli())} at the top level of your namespace.
}
It is also possible to call \code{local_use_cli()} inside a running
function, in which case the flag only applies within that function.
}
\keyword{internal}
rlang/man/sym.Rd 0000644 0001762 0000144 00000004061 14175213516 013235 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sym.R
\name{sym}
\alias{sym}
\alias{syms}
\alias{data_sym}
\alias{data_syms}
\title{Create a symbol or list of symbols}
\usage{
sym(x)
syms(x)
data_sym(x)
data_syms(x)
}
\arguments{
\item{x}{For \code{sym()} and \code{data_sym()}, a string. For \code{syms()} and
\code{data_syms()}, a list of strings.}
}
\value{
For \code{sym()} and \code{syms()}, a symbol or list of symbols. For
\code{data_sym()} and \code{data_syms()}, calls of the form \code{.data$foo}.
}
\description{
Symbols are a kind of \link[=topic-defuse]{defused expression} that
represent objects in environments.
\itemize{
\item \code{sym()} and \code{syms()} take strings as input and turn them into
symbols.
\item \code{data_sym()} and \code{data_syms()} create calls of the form
\code{.data$foo} instead of symbols. Subsetting the \code{\link{.data}} pronoun
is more robust when you expect a data-variable. See
\ifelse{html}{\link[=topic-data-mask-ambiguity]{The data mask ambiguity}}{\link[=topic-data-mask-ambiguity]{The data mask ambiguity}}.
}
Only tidy eval APIs support the \code{\link{.data}} pronoun. With base R
functions, use simple symbols created with \code{sym()} or \code{syms()}.
}
\examples{
# Create a symbol
sym("cyl")
# Create a list of symbols
syms(c("cyl", "am"))
# Symbolised names refer to variables
eval(sym("cyl"), mtcars)
# Beware of scoping issues
Cyl <- "wrong"
eval(sym("Cyl"), mtcars)
# Data symbols are explicitly scoped in the data mask
try(eval_tidy(data_sym("Cyl"), mtcars))
# These can only be used with tidy eval functions
try(eval(data_sym("Cyl"), mtcars))
# The empty string returns the missing argument:
sym("")
# This way sym() and as_string() are inverse of each other:
as_string(missing_arg())
sym(as_string(missing_arg()))
}
\seealso{
\itemize{
\item \ifelse{html}{\link[=topic-defuse]{Defusing R expressions}}{\link[=topic-defuse]{Defusing R expressions}}
\item \ifelse{html}{\link[=topic-metaprogramming]{Metaprogramming patterns}}{\link[=topic-metaprogramming]{Metaprogramming patterns}}
}
}
rlang/man/names2.Rd 0000644 0001762 0000144 00000001725 14175213516 013616 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/attr.R
\name{names2}
\alias{names2}
\alias{names2<-}
\title{Get names of a vector}
\usage{
names2(x)
names2(x) <- value
}
\arguments{
\item{x}{A vector.}
\item{value}{New names.}
}
\description{
\code{names2()} always returns a character vector, even when an
object does not have a \code{names} attribute. In this case, it returns
a vector of empty names \code{""}. It also standardises missing names to
\code{""}.
The replacement variant \verb{names2<-} never adds \code{NA} names and
instead fills unnamed vectors with \code{""}.
}
\examples{
names2(letters)
# It also takes care of standardising missing names:
x <- set_names(1:3, c("a", NA, "b"))
names2(x)
# Replacing names with the base `names<-` function may introduce
# `NA` values when the vector is unnamed:
x <- 1:3
names(x)[1:2] <- "foo"
names(x)
# Use the `names2<-` variant to avoid this
x <- 1:3
names2(x)[1:2] <- "foo"
names(x)
}
rlang/man/is_environment.Rd 0000644 0001762 0000144 00000000614 13351410763 015462 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/types.R
\name{is_environment}
\alias{is_environment}
\alias{is_bare_environment}
\title{Is object an environment?}
\usage{
is_environment(x)
is_bare_environment(x)
}
\arguments{
\item{x}{object to test}
}
\description{
\code{is_bare_environment()} tests whether \code{x} is an environment without a s3 or
s4 class.
}
rlang/man/call_standardise.Rd 0000644 0001762 0000144 00000003003 14175213516 015714 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{call_standardise}
\alias{call_standardise}
\title{Standardise a call}
\usage{
call_standardise(call, env = caller_env())
}
\arguments{
\item{call}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}}
\item{env}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}}
}
\value{
A quosure if \code{call} is a quosure, a raw call otherwise.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
Deprecated in rlang 0.4.11 in favour of \code{\link[=call_match]{call_match()}}.
\code{call_standardise()} was designed for call wrappers that include an
environment like formulas or quosures. The function definition was
plucked from that environment. However in practice it is rare to
use it with wrapped calls, and then it's easy to forget to supply
the environment. For these reasons, we have designed \code{\link[=call_match]{call_match()}}
as a simpler wrapper around \code{\link[=match.call]{match.call()}}.
This is essentially equivalent to \code{\link[base:match.call]{base::match.call()}}, but with
experimental handling of primitive functions.
}
\keyword{internal}
rlang/man/call_name.Rd 0000644 0001762 0000144 00000004075 14175213516 014345 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/call.R
\name{call_name}
\alias{call_name}
\alias{call_ns}
\alias{is_call_simple}
\title{Extract function name or namespace of a call}
\usage{
call_name(call)
call_ns(call)
is_call_simple(x, ns = NULL)
}
\arguments{
\item{call}{A defused call.}
\item{x}{An object to test.}
\item{ns}{Whether call is namespaced. If \code{NULL}, \code{is_call_simple()}
is insensitive to namespaces. If \code{TRUE}, \code{is_call_simple()}
detects namespaced calls. If \code{FALSE}, it detects unnamespaced
calls.}
}
\value{
The function name or namespace as a string, or \code{NULL} if
the call is not named or namespaced.
}
\description{
\code{call_name()} and \code{call_ns()} extract the function name or
namespace of \emph{simple} calls as a string. They return \code{NULL} for
complex calls.
\itemize{
\item Simple calls: \code{foo()}, \code{bar::foo()}.
\item Complex calls: \code{foo()()}, \code{bar::foo}, \code{foo$bar()}, \code{(function() NULL)()}.
}
The \code{is_call_simple()} predicate helps you determine whether a call
is simple. There are two invariants you can count on:
\enumerate{
\item If \code{is_call_simple(x)} returns \code{TRUE}, \code{call_name(x)} returns a
string. Otherwise it returns \code{NULL}.
\item If \code{is_call_simple(x, ns = TRUE)} returns \code{TRUE}, \code{call_ns()}
returns a string. Otherwise it returns \code{NULL}.
}
}
\examples{
# Is the function named?
is_call_simple(quote(foo()))
is_call_simple(quote(foo[[1]]()))
# Is the function namespaced?
is_call_simple(quote(list()), ns = TRUE)
is_call_simple(quote(base::list()), ns = TRUE)
# Extract the function name from quoted calls:
call_name(quote(foo(bar)))
call_name(quo(foo(bar)))
# Namespaced calls are correctly handled:
call_name(quote(base::matrix(baz)))
# Anonymous and subsetted functions return NULL:
call_name(quote(foo$bar()))
call_name(quote(foo[[bar]]()))
call_name(quote(foo()()))
# Extract namespace of a call with call_ns():
call_ns(quote(base::bar()))
# If not namespaced, call_ns() returns NULL:
call_ns(quote(bar()))
}
rlang/man/eval_tidy.Rd 0000644 0001762 0000144 00000011505 14175213516 014406 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/eval-tidy.R
\name{eval_tidy}
\alias{eval_tidy}
\title{Evaluate an expression with quosures and pronoun support}
\usage{
eval_tidy(expr, data = NULL, env = caller_env())
}
\arguments{
\item{expr}{An \link[=topic-defuse]{expression} or
\link[=topic-quosure]{quosure} to evaluate.}
\item{data}{A data frame, or named list or vector. Alternatively, a
data mask created with \code{\link[=as_data_mask]{as_data_mask()}} or
\code{\link[=new_data_mask]{new_data_mask()}}. Objects in \code{data} have priority over those in
\code{env}. See the section about data masking.}
\item{env}{The environment in which to evaluate \code{expr}. This
environment is not applicable for quosures because they have
their own environments.}
}
\description{
\code{eval_tidy()} is a variant of \code{\link[base:eval]{base::eval()}} that powers the tidy
evaluation framework. Like \code{eval()} it accepts user data as
argument. Whereas \code{eval()} simply transforms the data to an
environment, \code{eval_tidy()} transforms it to a \link[=topic-data-mask]{data mask} with \code{\link[=as_data_mask]{as_data_mask()}}. Evaluating in a data
mask enables the following features:
\itemize{
\item \link[=topic-quosure]{Quosures}. Quosures are expressions bundled with
an environment. If \code{data} is supplied, objects in the data mask
always have precedence over the quosure environment, i.e. the
data masks the environment.
\item \link[=.data]{Pronouns}. If \code{data} is supplied, the \code{.env} and \code{.data}
pronouns are installed in the data mask. \code{.env} is a reference to
the calling environment and \code{.data} refers to the \code{data}
argument. These pronouns are an escape hatch for the \link[=topic-data-mask-ambiguity]{data mask ambiguity} problem.
}
}
\section{When should eval_tidy() be used instead of eval()?}{
\code{base::eval()} is sufficient for simple evaluation. Use
\code{eval_tidy()} when you'd like to support expressions referring to
the \code{.data} pronoun, or when you need to support quosures.
If you're evaluating an expression captured with
\link[=topic-inject]{injection} support, it is recommended to use
\code{eval_tidy()} because users may inject quosures.
Note that unwrapping a quosure with \code{\link[=quo_get_expr]{quo_get_expr()}} does not
guarantee that there is no quosures inside the expression. Quosures
might be unquoted anywhere in the expression tree. For instance,
the following does not work reliably in the presence of nested
quosures:\preformatted{my_quoting_fn <- function(x) \{
x <- enquo(x)
expr <- quo_get_expr(x)
env <- quo_get_env(x)
eval(expr, env)
\}
# Works:
my_quoting_fn(toupper(letters))
# Fails because of a nested quosure:
my_quoting_fn(toupper(!!quo(letters)))
}
}
\section{Stack semantics of \code{eval_tidy()}}{
\code{eval_tidy()} always evaluates in a data mask, even when \code{data} is
\code{NULL}. Because of this, it has different stack semantics than
\code{\link[base:eval]{base::eval()}}:
\itemize{
\item Lexical side effects, such as assignment with \verb{<-}, occur in the
mask rather than \code{env}.
\item Functions that require the evaluation environment to correspond
to a frame on the call stack do not work. This is why \code{return()}
called from a quosure does not work.
\item The mask environment creates a new branch in the tree
representation of backtraces (which you can visualise in a
\code{\link[=browser]{browser()}} session with \code{lobstr::cst()}).
}
See also \code{\link[=eval_bare]{eval_bare()}} for more information about these differences.
}
\examples{
# With simple defused expressions eval_tidy() works the same way as
# eval():
fruit <- "apple"
vegetable <- "potato"
expr <- quote(paste(fruit, vegetable, sep = " or "))
expr
eval(expr)
eval_tidy(expr)
# Both accept a data mask as argument:
data <- list(fruit = "banana", vegetable = "carrot")
eval(expr, data)
eval_tidy(expr, data)
# The main difference is that eval_tidy() supports quosures:
with_data <- function(data, expr) {
quo <- enquo(expr)
eval_tidy(quo, data)
}
with_data(NULL, fruit)
with_data(data, fruit)
# eval_tidy() installs the `.data` and `.env` pronouns to allow
# users to be explicit about variable references:
with_data(data, .data$fruit)
with_data(data, .env$fruit)
}
\seealso{
\itemize{
\item \ifelse{html}{\link[=topic-data-mask]{What is data-masking and why do I need \{\{?}}{\link[=topic-data-mask]{What is data-masking and why do I need curly-curly?}}.
\item \ifelse{html}{\link[=topic-quosure]{What are quosures and when are they needed?}}{\link[=topic-quosure]{What are quosures and when are they needed?}}.
\item \ifelse{html}{\link[=topic-defuse]{Defusing R expressions}}{\link[=topic-defuse]{Defusing R expressions}}.
\item \code{\link[=new_data_mask]{new_data_mask()}} and \code{\link[=as_data_mask]{as_data_mask()}} for manually creating data masks.
}
}
rlang/man/rlang_backtrace_on_error.Rd 0000644 0001762 0000144 00000005652 14175213516 017443 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-abort.R
\name{rlang_backtrace_on_error}
\alias{rlang_backtrace_on_error}
\alias{add_backtrace}
\title{Display backtrace on error}
\description{
rlang errors carry a backtrace that can be inspected by calling
\code{\link[=last_error]{last_error()}}. You can also control the default display of the
backtrace by setting the option \code{rlang_backtrace_on_error} to one
of the following values:
\itemize{
\item \code{"none"} show nothing.
\item \code{"reminder"}, the default in interactive sessions, displays a reminder that
you can see the backtrace with \code{\link[=last_error]{last_error()}}.
\item \code{"branch"} displays a simplified backtrace.
\item \code{"collapse"} displays a collapsed backtrace tree.
\item \code{"full"}, the default in non-interactive sessions, displays the full tree.
}
rlang errors are normally thrown with \code{\link[=abort]{abort()}}. If you promote
base errors to rlang errors with \code{\link[=global_entrace]{global_entrace()}},
\code{rlang_backtrace_on_error} applies to all errors.
}
\section{Promote base errors to rlang errors}{
You can use \code{options(error = rlang::entrace)} to promote base errors to
rlang errors. This does two things:
\itemize{
\item It saves the base error as an rlang object so you can call \code{\link[=last_error]{last_error()}}
to print the backtrace or inspect its data.
\item It prints the backtrace for the current error according to the
\code{rlang_backtrace_on_error} option.
}
}
\section{Errors in RMarkdown}{
The display of errors depends on whether they're expected (i.e.
chunk option \code{error = TRUE}) or unexpected:
\itemize{
\item Expected errors are controlled by the global option
\code{"rlang_backtrace_on_error_report"} (note the \verb{_report} suffix).
The default is \code{"none"} so that your expected errors don't
include a reminder to run \code{rlang::last_error()}. Customise this
option if you want to demonstrate what the error backtrace will
look like.
You can also use \code{\link[=last_error]{last_error()}} to display the trace like you
would in your session, but it currently only works in the next
chunk.
\item Unexpected errors are controlled by the global option
\code{"rlang_backtrace_on_error"}. The default is \code{"branch"} so you'll
see a simplified backtrace in the knitr output to help you figure
out what went wrong.
}
When knitr is running (as determined by the \code{knitr.in.progress}
global option), the default top environment for backtraces is set
to the chunk environment \code{knitr::knit_global()}. This ensures that
the part of the call stack belonging to knitr does not end up in
backtraces. If needed, you can override this by setting the
\code{rlang_trace_top_env} global option.
}
\examples{
# Display a simplified backtrace on error for both base and rlang
# errors:
# options(
# rlang_backtrace_on_error = "branch",
# error = rlang::entrace
# )
# stop("foo")
}
rlang/man/is_symbol.Rd 0000644 0001762 0000144 00000000526 13351410763 014425 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sym.R
\name{is_symbol}
\alias{is_symbol}
\title{Is object a symbol?}
\usage{
is_symbol(x, name = NULL)
}
\arguments{
\item{x}{An object to test.}
\item{name}{An optional name or vector of names that the symbol
should match.}
}
\description{
Is object a symbol?
}
rlang/man/bytes-class.Rd 0000644 0001762 0000144 00000002117 14175213516 014656 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bytes.R
\name{bytes-class}
\alias{bytes-class}
\alias{as_bytes}
\alias{parse_bytes}
\title{Human readable memory sizes}
\usage{
as_bytes(x)
parse_bytes(x)
}
\arguments{
\item{x}{A numeric or character vector. Character representations can use
shorthand sizes (see examples).}
}
\description{
Construct, manipulate and display vectors of byte sizes. These are numeric
vectors, so you can compare them numerically, but they can also be compared
to human readable values such as '10MB'.
\itemize{
\item \code{parse_bytes()} takes a character vector of human-readable bytes
and returns a structured bytes vector.
\item \code{as_bytes()} is a generic conversion function for objects
representing bytes.
}
Note: A \code{bytes()} constructor will be exported soon.
}
\details{
These memory sizes are always assumed to be base 1024, rather than 1000.
}
\examples{
parse_bytes("1")
parse_bytes("1K")
parse_bytes("1Kb")
parse_bytes("1KiB")
parse_bytes("1MB")
parse_bytes("1KB") < "1MB"
sum(parse_bytes(c("1MB", "5MB", "500KB")))
}
rlang/man/op-na-default.Rd 0000644 0001762 0000144 00000001700 14175213516 015056 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/operators.R
\name{op-na-default}
\alias{op-na-default}
\alias{\%|\%}
\title{Replace missing values}
\usage{
x \%|\% y
}
\arguments{
\item{x}{The original values.}
\item{y}{The replacement values. Must be of length 1 or the same length as \code{x}.}
}
\description{
\strong{Note}: This operator is now out of scope for rlang. It will be
replaced by a vctrs-powered operator (probably in the \href{https://github.com/tidyverse/funs}{funs package}) at which point the
rlang version of \verb{\%|\%} will be deprecated.
This infix function is similar to \code{\%||\%} but is vectorised
and provides a default value for missing elements. It is faster
than using \code{\link[base:ifelse]{base::ifelse()}} and does not perform type conversions.
}
\examples{
c("a", "b", NA, "c") \%|\% "default"
c(1L, NA, 3L, NA, NA) \%|\% (6L:10L)
}
\seealso{
\link{op-null-default}
}
\keyword{internal}
rlang/man/is_empty.Rd 0000644 0001762 0000144 00000000524 13351410454 014251 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/types.R
\name{is_empty}
\alias{is_empty}
\title{Is object an empty vector or NULL?}
\usage{
is_empty(x)
}
\arguments{
\item{x}{object to test}
}
\description{
Is object an empty vector or NULL?
}
\examples{
is_empty(NULL)
is_empty(list())
is_empty(list(NULL))
}
rlang/man/inject.Rd 0000644 0001762 0000144 00000003114 14175213516 013677 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/eval.R
\name{inject}
\alias{inject}
\title{Inject objects in an R expression}
\usage{
inject(expr, env = caller_env())
}
\arguments{
\item{expr}{An argument to evaluate. This argument is immediately
evaluated in \code{env} (the current environment by default) with
injected objects and expressions.}
\item{env}{The environment in which to evaluate \code{expr}. Defaults to
the current environment. For expert use only.}
}
\description{
\code{inject()} evaluates an expression with \link[=quasiquotation]{injection}
support. There are three main usages:
\itemize{
\item \link[=!!!]{Splicing} lists of arguments in a function call.
\item Inline objects or other expressions in an expression with \verb{!!}
and \verb{!!!}. For instance to create functions or formulas
programmatically.
\item Pass arguments to NSE functions that \link[=nse-defuse]{defuse} their
arguments without injection support (see for instance
\code{\link[=enquo0]{enquo0()}}). You can use \code{{{ arg }}} with functions documented
to support quosures. Otherwise, use \code{!!enexpr(arg)}.
}
}
\examples{
# inject() simply evaluates its argument with injection
# support. These expressions are equivalent:
2 * 3
inject(2 * 3)
inject(!!2 * !!3)
# Injection with `!!` can be useful to insert objects or
# expressions within other expressions, like formulas:
lhs <- sym("foo")
rhs <- sym("bar")
inject(!!lhs ~ !!rhs + 10)
# Injection with `!!!` splices lists of arguments in function
# calls:
args <- list(na.rm = TRUE, finite = 0.2)
inject(mean(1:10, !!!args))
}
rlang/man/exprs_auto_name.Rd 0000644 0001762 0000144 00000002057 14175213516 015621 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nse-defuse.R
\name{exprs_auto_name}
\alias{exprs_auto_name}
\alias{quos_auto_name}
\title{Ensure that all elements of a list of expressions are named}
\usage{
exprs_auto_name(
exprs,
...,
repair_auto = c("minimal", "unique"),
repair_quiet = FALSE
)
quos_auto_name(quos)
}
\arguments{
\item{exprs}{A list of expressions.}
\item{...}{These dots are for future extensions and must be empty.}
\item{repair_auto}{Whether to repair the automatic names. By
default, minimal names are returned. See \code{?vctrs::vec_as_names}
for information about name repairing.}
\item{repair_quiet}{Whether to inform user about repaired names.}
\item{quos}{A list of quosures.}
}
\description{
This gives default names to unnamed elements of a list of
expressions (or expression wrappers such as formulas or
quosures). \code{exprs_auto_name()} deparses the expressions with
\code{\link[=expr_name]{expr_name()}} by default. \code{quos_auto_name()} deparses with
\code{\link[=quo_name]{quo_name()}}.
}
rlang/man/local_bindings.Rd 0000644 0001762 0000144 00000003010 14127057575 015375 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-binding.R
\name{local_bindings}
\alias{local_bindings}
\alias{with_bindings}
\title{Temporarily change bindings of an environment}
\usage{
local_bindings(..., .env = .frame, .frame = caller_env())
with_bindings(.expr, ..., .env = caller_env())
}
\arguments{
\item{...}{Pairs of names and values. These dots support splicing
(with value semantics) and name unquoting.}
\item{.env}{An environment.}
\item{.frame}{The frame environment that determines the scope of
the temporary bindings. When that frame is popped from the call
stack, bindings are switched back to their original values.}
\item{.expr}{An expression to evaluate with temporary bindings.}
}
\value{
\code{local_bindings()} returns the values of old bindings
invisibly; \code{with_bindings()} returns the value of \code{expr}.
}
\description{
\itemize{
\item \code{local_bindings()} temporarily changes bindings in \code{.env} (which
is by default the caller environment). The bindings are reset to
their original values when the current frame (or an arbitrary one
if you specify \code{.frame}) goes out of scope.
\item \code{with_bindings()} evaluates \code{expr} with temporary bindings. When
\code{with_bindings()} returns, bindings are reset to their original
values. It is a simple wrapper around \code{local_bindings()}.
}
}
\examples{
foo <- "foo"
bar <- "bar"
# `foo` will be temporarily rebinded while executing `expr`
with_bindings(paste(foo, bar), foo = "rebinded")
paste(foo, bar)
}
rlang/man/cnd.Rd 0000644 0001762 0000144 00000004552 14176512327 013201 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd.R
\name{cnd}
\alias{cnd}
\alias{error_cnd}
\alias{warning_cnd}
\alias{message_cnd}
\title{Create a condition object}
\usage{
cnd(class, ..., message = "", call = NULL, use_cli_format = NULL)
error_cnd(
class = NULL,
...,
message = "",
call = NULL,
trace = NULL,
parent = NULL,
use_cli_format = NULL
)
warning_cnd(
class = NULL,
...,
message = "",
call = NULL,
use_cli_format = NULL
)
message_cnd(
class = NULL,
...,
message = "",
call = NULL,
use_cli_format = NULL
)
}
\arguments{
\item{class}{The condition subclass.}
\item{...}{<\link[=dyn-dots]{dynamic}> Named data fields stored inside
the condition object.}
\item{message}{A default message to inform the user about the
condition when it is signalled.}
\item{call}{A function call to be included in the error message.
If an execution environment of a running function, the
corresponding function call is retrieved.}
\item{use_cli_format}{Whether to use the cli package to format
\code{message}. See \code{\link[=local_use_cli]{local_use_cli()}}.}
\item{trace}{A \code{trace} object created by \code{\link[=trace_back]{trace_back()}}.}
\item{parent}{A parent condition object.}
}
\description{
These constructors create subclassed conditions, the objects that
power the error, warning, and message system in R.
\itemize{
\item \code{cnd()} creates bare conditions that only inherit from
\code{condition}.
\item Conditions created with \code{error_cnd()}, \code{warning_cnd()}, and
\code{message_cnd()} inherit from \code{"error"}, \code{"warning"}, or \code{"message"}.
\item \code{error_cnd()} creates subclassed errors. See
\code{\link[=rlang_error]{"rlang_error"}}.
}
Use \code{\link[=cnd_signal]{cnd_signal()}} to emit the relevant signal for a particular
condition class.
}
\examples{
# Create a condition inheriting only from the S3 class "foo":
cnd <- cnd("foo")
# Signal the condition to potential handlers. Since this is a bare
# condition the signal has no effect if no handlers are set up:
cnd_signal(cnd)
# When a relevant handler is set up, the signal transfers control
# to the handler
with_handlers(cnd_signal(cnd), foo = function(c) "caught!")
tryCatch(cnd_signal(cnd), foo = function(c) "caught!")
}
\seealso{
\code{\link[=cnd_signal]{cnd_signal()}}, \code{\link[=try_fetch]{try_fetch()}}.
}
\keyword{internal}
rlang/man/qq_show.Rd 0000644 0001762 0000144 00000002347 14175213516 014113 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nse-inject.R
\name{qq_show}
\alias{qq_show}
\title{Show injected expression}
\arguments{
\item{expr}{An expression involving \link[=topic-inject]{injection operators}.}
}
\description{
\code{qq_show()} helps examining \link[=topic-inject]{injected expressions}
inside a function. This is useful for learning about injection and
for debugging injection code.
}
\section{Examples}{
\code{qq_show()} shows the intermediary expression before it is
evaluated by R:\if{html}{\out{
}}
It is especially useful inside functions to reveal what an injected
expression looks like:\if{html}{\out{
}}\preformatted{my_mean <- function(data, var) \{
qq_show(data \%>\% dplyr::summarise(mean(\{\{ var \}\})))
\}
mtcars \%>\% my_mean(cyl)
#> data \%>\% dplyr::summarise(mean(^cyl))
}\if{html}{\out{
}}
}
\seealso{
\itemize{
\item \ifelse{html}{\link[=topic-inject]{Injecting with !!, !!!, and glue syntax}}{\link[=topic-inject]{Injecting with !!, !!!, and glue syntax}}
}
}
rlang/man/as_closure.Rd 0000644 0001762 0000144 00000003035 14175213516 014564 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fn.R
\name{as_closure}
\alias{as_closure}
\title{Transform to a closure}
\usage{
as_closure(x, env = caller_env())
}
\arguments{
\item{x}{A function or formula.
If a \strong{function}, it is used as is.
If a \strong{formula}, e.g. \code{~ .x + 2}, it is converted to a function
with up to two arguments: \code{.x} (single argument) or \code{.x} and \code{.y}
(two arguments). The \code{.} placeholder can be used instead of \code{.x}.
This allows you to create very compact anonymous functions (lambdas) with up
to two inputs. Functions created from formulas have a special
class. Use \code{is_lambda()} to test for it.
If a \strong{string}, the function is looked up in \code{env}. Note that
this interface is strictly for user convenience because of the
scoping issues involved. Package developers should avoid
supplying functions by name and instead supply them by value.}
\item{env}{Environment in which to fetch the function in case \code{x}
is a string.}
}
\description{
\code{as_closure()} is like \code{\link[=as_function]{as_function()}} but also wraps primitive
functions inside closures. Some special control flow primitives
like \code{if}, \code{for}, or \code{break} can't be wrapped and will cause an
error.
}
\examples{
# Primitive functions are regularised as closures
as_closure(list)
as_closure("list")
# Operators have `.x` and `.y` as arguments, just like lambda
# functions created with the formula syntax:
as_closure(`+`)
as_closure(`~`)
}
\keyword{internal}
rlang/man/expr.Rd 0000644 0001762 0000144 00000003026 14175213516 013403 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nse-defuse.R
\name{expr}
\alias{expr}
\title{Defuse an R expression}
\arguments{
\item{expr}{An expression to defuse.}
}
\description{
\code{expr()} \link[=topic-defuse]{defuses} an R expression with
\link[=injection-operator]{injection} support.
It is equivalent to \code{\link[base:bquote]{base::bquote()}}.
}
\examples{
# R normally returns the result of an expression
1 + 1
# `expr()` defuses the expression that you have supplied and
# returns it instead of its value
expr(1 + 1)
expr(toupper(letters))
# It supports _injection_ with `!!` and `!!!`. This is a convenient
# way of modifying part of an expression by injecting other
# objects.
var <- "cyl"
expr(with(mtcars, mean(!!sym(var))))
vars <- c("cyl", "am")
expr(with(mtcars, c(!!!syms(vars))))
# Compare to the normal way of building expressions
call("with", call("mean", sym(var)))
call("with", call2("c", !!!syms(vars)))
}
\seealso{
\itemize{
\item \ifelse{html}{\link[=topic-defuse]{Defusing R expressions}}{\link[=topic-defuse]{Defusing R expressions}} for an overview.
\item \code{\link[=enquo]{enquo()}} to defuse non-local expressions from function
arguments.
\item \link[=defusing-advanced]{Advanced defusal operators}.
\item \code{\link[=sym]{sym()}} and \code{\link[=call2]{call2()}} for building expressions (symbols and calls
respectively) programmatically.
\item \code{\link[base:eval]{base::eval()}} and \code{\link[=eval_bare]{eval_bare()}} for resuming evaluation
of a defused expression.
}
}
rlang/man/lang.Rd 0000644 0001762 0000144 00000001452 14175213516 013347 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{lang}
\alias{lang}
\title{Create a call}
\usage{
lang(.fn, ..., .ns = NULL)
}
\arguments{
\item{.fn}{Function to call. Must be a callable object: a string,
symbol, call, or a function.}
\item{...}{<\link[=dyn-dots]{dynamic}> Arguments for the function
call. Empty arguments are preserved.}
\item{.ns}{Namespace with which to prefix \code{.fn}. Must be a string
or symbol.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
These functions are deprecated, please use \code{\link[=call2]{call2()}} and
\code{\link[=new_call]{new_call()}} instead.
}
\keyword{internal}
rlang/man/is_callable.Rd 0000644 0001762 0000144 00000002263 14137447476 014675 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/call.R
\name{is_callable}
\alias{is_callable}
\title{Is an object callable?}
\usage{
is_callable(x)
}
\arguments{
\item{x}{An object to test.}
}
\description{
A callable object is an object that can appear in the function
position of a call (as opposed to argument position). This includes
\link[=is_symbolic]{symbolic objects} that evaluate to a function or
literal functions embedded in the call.
}
\details{
Note that strings may look like callable objects because
expressions of the form \code{"list"()} are valid R code. However,
that's only because the R parser transforms strings to symbols. It
is not legal to manually set language heads to strings.
}
\examples{
# Symbolic objects and functions are callable:
is_callable(quote(foo))
is_callable(base::identity)
# node_poke_car() lets you modify calls without any checking:
lang <- quote(foo(10))
node_poke_car(lang, current_env())
# Use is_callable() to check an input object is safe to put as CAR:
obj <- base::identity
if (is_callable(obj)) {
lang <- node_poke_car(lang, obj)
} else {
abort("`obj` must be callable")
}
eval_bare(lang)
}
\keyword{internal}
rlang/man/obj_address.Rd 0000644 0001762 0000144 00000000500 14175213516 014676 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/obj.R
\name{obj_address}
\alias{obj_address}
\title{Address of an R object}
\usage{
obj_address(x)
}
\arguments{
\item{x}{Any R object.}
}
\value{
Its address in memory in a string.
}
\description{
Address of an R object
}
\keyword{internal}
rlang/man/are_na.Rd 0000644 0001762 0000144 00000003327 14175213516 013656 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vec-na.R
\name{are_na}
\alias{are_na}
\alias{is_na}
\alias{is_lgl_na}
\alias{is_int_na}
\alias{is_dbl_na}
\alias{is_chr_na}
\alias{is_cpl_na}
\title{Test for missing values}
\usage{
are_na(x)
is_na(x)
is_lgl_na(x)
is_int_na(x)
is_dbl_na(x)
is_chr_na(x)
is_cpl_na(x)
}
\arguments{
\item{x}{An object to test}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#questioning}{\figure{lifecycle-questioning.svg}{options: alt='[Questioning]'}}}{\strong{[Questioning]}}
\code{are_na()} checks for missing values in a vector and is equivalent
to \code{\link[base:NA]{base::is.na()}}. It is a vectorised predicate, meaning that its
output is always the same length as its input. On the other hand,
\code{is_na()} is a scalar predicate and always returns a scalar
boolean, \code{TRUE} or \code{FALSE}. If its input is not scalar, it returns
\code{FALSE}. Finally, there are typed versions that check for
particular \link[=missing]{missing types}.
}
\details{
The scalar predicates accept non-vector inputs. They are equivalent
to \code{\link[=is_null]{is_null()}} in that respect. In contrast the vectorised
predicate \code{are_na()} requires a vector input since it is defined
over vector values.
}
\section{Life cycle}{
These functions might be moved to the vctrs package at some
point. This is why they are marked as questioning.
}
\examples{
# are_na() is vectorised and works regardless of the type
are_na(c(1, 2, NA))
are_na(c(1L, NA, 3L))
# is_na() checks for scalar input and works for all types
is_na(NA)
is_na(na_dbl)
is_na(character(0))
# There are typed versions as well:
is_lgl_na(NA)
is_lgl_na(na_dbl)
}
\keyword{internal}
rlang/man/englue.Rd 0000644 0001762 0000144 00000003226 14175213516 013706 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nse-inject.R
\name{englue}
\alias{englue}
\title{Defuse function arguments with glue}
\usage{
englue(x)
}
\arguments{
\item{x}{A string to interpolate with glue operators.}
}
\description{
\code{englue()} creates a string with the \link[=glue-operators]{glue operators} \verb{\{} and \verb{\{\{}. These operators are
normally used to inject names within \link[=dyn-dots]{dynamic dots}.
\code{englue()} makes them available anywhere within a function.
\code{englue()} must be used inside a function. \code{englue("{{ var }}")}
\link[=topic-defuse]{defuses} the argument \code{var} and transforms it to a
string using the default name operation.
}
\details{
\code{englue("{{ var }}")} is equivalent to \code{as_label(enquo(var))}. It
\link[=topic-defuse]{defuses} \code{arg} and transforms the expression to a
string with \code{\link[=as_label]{as_label()}}.
In dynamic dots, using only \verb{\{} is allowed. In \code{englue()} you must
use \verb{\{\{} at least once. Use \code{glue::glue()} for simple
interpolation.
Before using \code{englue()} in a package, first ensure that glue is
installed by adding it to your \verb{Imports:} section.\if{html}{\out{
}}
}
\examples{
g <- function(var) englue("{{ var }}")
g(cyl)
g(1 + 1)
g(!!letters)
# These are equivalent to
as_label(quote(cyl))
as_label(quote(1 + 1))
as_label(letters)
}
\seealso{
\itemize{
\item \ifelse{html}{\link[=topic-inject]{Injecting with !!, !!!, and glue syntax}}{\link[=topic-inject]{Injecting with !!, !!!, and glue syntax}}
}
}
rlang/man/op-get-attr.Rd 0000644 0001762 0000144 00000001472 14127057575 014603 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/operators.R
\name{op-get-attr}
\alias{op-get-attr}
\alias{\%@\%}
\alias{\%@\%<-}
\title{Infix attribute accessor and setter}
\usage{
x \%@\% name
x \%@\% name <- value
}
\arguments{
\item{x}{Object}
\item{name}{Attribute name}
\item{value}{New value for attribute \code{name}.}
}
\description{
This operator extracts or sets attributes for regular objects and
S4 fields for S4 objects.
}
\examples{
# Unlike `@`, this operator extracts attributes for any kind of
# objects:
factor(1:3) \%@\% "levels"
mtcars \%@\% class
mtcars \%@\% class <- NULL
mtcars
# It also works on S4 objects:
.Person <- setClass("Person", slots = c(name = "character", species = "character"))
fievel <- .Person(name = "Fievel", species = "mouse")
fievel \%@\% name
}
rlang/man/cnd_type.Rd 0000644 0001762 0000144 00000001005 14127057575 014235 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd.R
\name{cnd_type}
\alias{cnd_type}
\title{What type is a condition?}
\usage{
cnd_type(cnd)
}
\arguments{
\item{cnd}{A condition object.}
}
\value{
A string, either \code{"condition"}, \code{"message"}, \code{"warning"},
\code{"error"} or \code{"interrupt"}.
}
\description{
Use \code{cnd_type()} to check what type a condition is.
}
\examples{
cnd_type(catch_cnd(abort("Abort!")))
cnd_type(catch_cnd(interrupt()))
}
\keyword{internal}
rlang/man/new_formula.Rd 0000644 0001762 0000144 00000000744 13351410454 014742 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/formula.R
\name{new_formula}
\alias{new_formula}
\title{Create a formula}
\usage{
new_formula(lhs, rhs, env = caller_env())
}
\arguments{
\item{lhs, rhs}{A call, name, or atomic vector.}
\item{env}{An environment.}
}
\value{
A formula object.
}
\description{
Create a formula
}
\examples{
new_formula(quote(a), quote(b))
new_formula(NULL, quote(b))
}
\seealso{
\code{\link[=new_quosure]{new_quosure()}}
}
rlang/man/empty_env.Rd 0000644 0001762 0000144 00000000732 14127057575 014444 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-special.R
\name{empty_env}
\alias{empty_env}
\title{Get the empty environment}
\usage{
empty_env()
}
\description{
The empty environment is the only one that does not have a parent.
It is always used as the tail of an environment chain such as the
search path (see \code{\link[=search_envs]{search_envs()}}).
}
\examples{
# Create environments with nothing in scope:
child_env(empty_env())
}
rlang/man/check_required.Rd 0000644 0001762 0000144 00000001643 14175213516 015405 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/arg.R
\name{check_required}
\alias{check_required}
\title{Check that argument is supplied}
\usage{
check_required(x, arg = caller_arg(x), call = caller_env())
}
\arguments{
\item{x}{A function argument. Must be a symbol.}
\item{arg}{An argument name as a string. This argument
will be mentioned in error messages as the input that is at the
origin of a problem.}
\item{call}{The execution environment of a currently
running function, e.g. \code{caller_env()}. The function will be
mentioned in error messages as the source of the error. See the
\code{call} argument of \code{\link[=abort]{abort()}} for more information.}
}
\description{
Throws an error if \code{x} is missing.
}
\examples{
f <- function(x) {
check_required(x)
}
# Fails because `x` is not supplied
try(f())
# Succeeds
f(NULL)
}
\seealso{
\code{\link[=arg_match]{arg_match()}}
}
rlang/man/is_weakref.Rd 0000644 0001762 0000144 00000000420 14127057575 014547 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/weakref.R
\name{is_weakref}
\alias{is_weakref}
\title{Is object a weak reference?}
\usage{
is_weakref(x)
}
\arguments{
\item{x}{An object to test.}
}
\description{
Is object a weak reference?
}
rlang/man/call_fn.Rd 0000644 0001762 0000144 00000001206 14175213516 014021 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{call_fn}
\alias{call_fn}
\title{Extract function from a call}
\usage{
call_fn(call, env = caller_env())
}
\arguments{
\item{call, env}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
Deprecated in rlang 0.4.11.
}
\keyword{internal}
rlang/man/invoke.Rd 0000644 0001762 0000144 00000001366 14175213516 013725 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{invoke}
\alias{invoke}
\title{Invoke a function with a list of arguments}
\usage{
invoke(.fn, .args = list(), ..., .env = caller_env(), .bury = c(".fn", ""))
}
\arguments{
\item{.fn, args, ..., .env, .bury}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
Deprecated in rlang 0.4.0 in favour of \code{\link[=exec]{exec()}}.
}
\keyword{internal}
rlang/man/as_environment.Rd 0000644 0001762 0000144 00000002464 14175213516 015461 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env.R
\name{as_environment}
\alias{as_environment}
\title{Coerce to an environment}
\usage{
as_environment(x, parent = NULL)
}
\arguments{
\item{x}{An object to coerce.}
\item{parent}{A parent environment, \code{\link[=empty_env]{empty_env()}} by default. This
argument is only used when \code{x} is data actually coerced to an
environment (as opposed to data representing an environment, like
\code{NULL} representing the empty environment).}
}
\description{
\code{as_environment()} coerces named vectors (including lists) to an
environment. The names must be unique. If supplied an unnamed
string, it returns the corresponding package environment (see
\code{\link[=pkg_env]{pkg_env()}}).
}
\details{
If \code{x} is an environment and \code{parent} is not \code{NULL}, the
environment is duplicated before being set a new parent. The return
value is therefore a different environment than \code{x}.
}
\examples{
# Coerce a named vector to an environment:
env <- as_environment(mtcars)
# By default it gets the empty environment as parent:
identical(env_parent(env), empty_env())
# With strings it is a handy shortcut for pkg_env():
as_environment("base")
as_environment("rlang")
# With NULL it returns the empty environment:
as_environment(NULL)
}
rlang/man/is_true.Rd 0000644 0001762 0000144 00000000710 14137447476 014110 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/types.R
\name{is_true}
\alias{is_true}
\alias{is_false}
\title{Is object identical to TRUE or FALSE?}
\usage{
is_true(x)
is_false(x)
}
\arguments{
\item{x}{object to test}
}
\description{
These functions bypass R's automatic conversion rules and check
that \code{x} is literally \code{TRUE} or \code{FALSE}.
}
\examples{
is_true(TRUE)
is_true(1)
is_false(FALSE)
is_false(0)
}
rlang/man/expr_print.Rd 0000644 0001762 0000144 00000004140 14175213516 014615 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expr.R
\name{expr_print}
\alias{expr_print}
\alias{expr_deparse}
\title{Print an expression}
\usage{
expr_print(x, ...)
expr_deparse(x, ..., width = peek_option("width"))
}
\arguments{
\item{x}{An object or expression to print.}
\item{...}{Arguments passed to \code{expr_deparse()}.}
\item{width}{The width of the deparsed or printed expression.
Defaults to the global option \code{width}.}
}
\value{
\code{expr_deparse()} returns a character vector of lines.
\code{expr_print()} returns its input invisibly.
}
\description{
\code{expr_print()}, powered by \code{expr_deparse()}, is an alternative
printer for R expressions with a few improvements over the base R
printer.
\itemize{
\item It colourises \link[=nse-defuse]{quosures} according to their environment.
Quosures from the global environment are printed normally while
quosures from local environments are printed in unique colour (or
in italic when all colours are taken).
\item It wraps inlined objects in angular brackets. For instance, an
integer vector unquoted in a function call (e.g.
\code{expr(foo(!!(1:3)))}) is printed like this: \verb{foo()} while by default R prints the code to create that vector:
\code{foo(1:3)} which is ambiguous.
\item It respects the width boundary (from the global option \code{width})
in more cases.
}
}
\examples{
# It supports any object. Non-symbolic objects are always printed
# within angular brackets:
expr_print(1:3)
expr_print(function() NULL)
# Contrast this to how the code to create these objects is printed:
expr_print(quote(1:3))
expr_print(quote(function() NULL))
# The main cause of non-symbolic objects in expressions is
# quasiquotation:
expr_print(expr(foo(!!(1:3))))
# Quosures from the global environment are printed normally:
expr_print(quo(foo))
expr_print(quo(foo(!!quo(bar))))
# Quosures from local environments are colourised according to
# their environments (if you have crayon installed):
local_quo <- local(quo(foo))
expr_print(local_quo)
wrapper_quo <- local(quo(bar(!!local_quo, baz)))
expr_print(wrapper_quo)
}
rlang/man/expr_interp.Rd 0000644 0001762 0000144 00000001326 14175213516 014765 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{expr_interp}
\alias{expr_interp}
\title{Process unquote operators in a captured expression}
\usage{
expr_interp(x, env = NULL)
}
\arguments{
\item{x, env}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
\code{expr_interp()} is deprecated, please use \code{\link[=inject]{inject()}} instead.
}
\keyword{internal}
rlang/man/env_get.Rd 0000644 0001762 0000144 00000003074 14175213516 014057 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-binding.R
\name{env_get}
\alias{env_get}
\alias{env_get_list}
\title{Get an object in an environment}
\usage{
env_get(env = caller_env(), nm, default, inherit = FALSE, last = empty_env())
env_get_list(
env = caller_env(),
nms,
default,
inherit = FALSE,
last = empty_env()
)
}
\arguments{
\item{env}{An environment.}
\item{nm, nms}{Names of bindings. \code{nm} must be a single string.}
\item{default}{A default value in case there is no binding for \code{nm}
in \code{env}.}
\item{inherit}{Whether to look for bindings in the parent
environments.}
\item{last}{Last environment inspected when \code{inherit} is \code{TRUE}.
Can be useful in conjunction with \code{\link[base:ns-topenv]{base::topenv()}}.}
}
\value{
An object if it exists. Otherwise, throws an error.
}
\description{
\code{env_get()} extracts an object from an enviroment \code{env}. By
default, it does not look in the parent environments.
\code{env_get_list()} extracts multiple objects from an environment into
a named list.
}
\examples{
parent <- child_env(NULL, foo = "foo")
env <- child_env(parent, bar = "bar")
# This throws an error because `foo` is not directly defined in env:
# env_get(env, "foo")
# However `foo` can be fetched in the parent environment:
env_get(env, "foo", inherit = TRUE)
# You can also avoid an error by supplying a default value:
env_get(env, "foo", default = "FOO")
}
\seealso{
\code{\link[=env_cache]{env_cache()}} for a variant of \code{env_get()} designed to
cache a value in an environment.
}
rlang/man/last_error.Rd 0000644 0001762 0000144 00000001615 14175213516 014603 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-last.R
\name{last_error}
\alias{last_error}
\alias{last_trace}
\title{Last \code{abort()} error}
\usage{
last_error()
last_trace()
}
\description{
\itemize{
\item \code{last_error()} returns the last error entraced by \code{\link[=abort]{abort()}} or
\code{\link[=global_entrace]{global_entrace()}}. The error is printed with a backtrace in
simplified form.
\item \code{last_trace()} is a shortcut to return the backtrace stored in
the last error. This backtrace is printed in full form.
}
}
\seealso{
\itemize{
\item \code{\link{rlang_backtrace_on_error}} to control what is displayed when an
error is thrown.
\item \code{\link[=global_entrace]{global_entrace()}} to enable \code{last_error()} logging for all errors.
\item \code{\link[=last_warnings]{last_warnings()}} and \code{\link[=last_messages]{last_messages()}}.
}
}
rlang/man/new_call.Rd 0000644 0001762 0000144 00000000746 14175213516 014217 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/node.R
\name{new_call}
\alias{new_call}
\title{Create a new call from components}
\usage{
new_call(car, cdr = NULL)
}
\arguments{
\item{car}{The head of the call. It should be a
\link[=is_callable]{callable} object: a symbol, call, or literal
function.}
\item{cdr}{The tail of the call, i.e. a \link[=new_node]{pairlist} of
arguments.}
}
\description{
Create a new call from components
}
\keyword{internal}
rlang/man/splice.Rd 0000644 0001762 0000144 00000010535 14175213516 013707 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dots.R
\name{splice}
\alias{splice}
\alias{is_spliced}
\alias{is_spliced_bare}
\alias{dots_splice}
\title{Splice lists}
\usage{
splice(x)
is_spliced(x)
is_spliced_bare(x)
dots_splice(
...,
.ignore_empty = c("trailing", "none", "all"),
.preserve_empty = FALSE,
.homonyms = c("keep", "first", "last", "error"),
.check_assign = FALSE
)
}
\arguments{
\item{x}{A list to splice.}
\item{...}{Arguments to collect in a list. These dots are
\link[=dyn-dots]{dynamic}.}
\item{.ignore_empty}{Whether to ignore empty arguments. Can be one
of \code{"trailing"}, \code{"none"}, \code{"all"}. If \code{"trailing"}, only the
last argument is ignored if it is empty.}
\item{.preserve_empty}{Whether to preserve the empty arguments that
were not ignored. If \code{TRUE}, empty arguments are stored with
\code{\link[=missing_arg]{missing_arg()}} values. If \code{FALSE} (the default) an error is
thrown when an empty argument is detected.}
\item{.homonyms}{How to treat arguments with the same name. The
default, \code{"keep"}, preserves these arguments. Set \code{.homonyms} to
\code{"first"} to only keep the first occurrences, to \code{"last"} to keep
the last occurrences, and to \code{"error"} to raise an informative
error and indicate what arguments have duplicated names.}
\item{.check_assign}{Whether to check for \verb{<-} calls. When \code{TRUE} a
warning recommends users to use \code{=} if they meant to match a
function parameter or wrap the \verb{<-} call in curly braces otherwise.
This ensures assignments are explicit.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#questioning}{\figure{lifecycle-questioning.svg}{options: alt='[Questioning]'}}}{\strong{[Questioning]}}
\itemize{
\item \code{splice} marks an object to be spliced. It is equivalent to using
\verb{!!!} in a function taking \link[=dyn-dots]{dynamic dots}.
\item \code{dots_splice()} is like \code{\link[=dots_list]{dots_list()}} but automatically splices
list inputs.
}
}
\section{Standard splicing versus quoting splicing}{
The \verb{!!!} operator works differently in \emph{standard} functions taking
dots with \code{dots_list()} than in \emph{quoting} functions taking dots
with \code{\link[=enexprs]{enexprs()}} or \code{\link[=enquos]{enquos()}}.
\itemize{
\item In quoting functions \verb{!!!} disaggregates its argument (let's call
it \code{x}) into as many objects as there are elements in
\code{x}. E.g. \code{quo(foo(!!! c(1, 2)))} is completely equivalent to
\code{quo(foo(1, 2))}. The creation of those separate objects has an
overhead but is typically not important when manipulating calls
because function calls typically take a small number of
arguments.
\item In standard functions, disaggregating the spliced collection
would have a negative performance impact in cases where
\code{dots_list()} is used to build up data structures from user
inputs. To avoid this spliced inputs are marked with \code{\link[=splice]{splice()}}
and the final list is built with (the equivalent of)
\code{flatten_if(dots, is_spliced)}.
}
Most of the time you should not care about the difference. However
if you use a standard function taking tidy dots within a quoting
function, the \verb{!!!} operator will disaggregate its argument because
the behaviour of the quasiquoting function has priority. You might
then observe some performance cost in edge cases. Here is one
example where this would happen:\preformatted{purrr::rerun(10, dplyr::bind_rows(!!! x))
}
\code{purrr::rerun()} is a quoting function and \code{dplyr::bind_rows()} is
a standard function. Because \code{bind_rows()} is called \emph{inside}
\code{rerun()}, the list \code{x} will be disaggregated into a pairlist of
arguments. To avoid this you can use \code{splice()} instead:\preformatted{purrr::rerun(10, dplyr::bind_rows(splice(x)))
}
}
\section{Life cycle}{
\itemize{
\item \code{dots_splice()} is in the questioning stage. It is part of our
experiments with dots semantics. Compared to \code{dots_list()},
\code{dots_splice()} automatically splices lists. We now lean towards
adopting a single type of dots semantics (those of \code{dots_list()})
where splicing is explicit.
\item \code{splice()} is in the questioning stage. It is not clear whether it is
really needed as there are other ways to avoid the performance
issue discussed above.
}
}
\keyword{internal}
rlang/man/new_weakref.Rd 0000644 0001762 0000144 00000005054 14127057575 014735 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/weakref.R
\name{new_weakref}
\alias{new_weakref}
\title{Create a weak reference}
\usage{
new_weakref(key, value = NULL, finalizer = NULL, on_quit = FALSE)
}
\arguments{
\item{key}{The key for the weak reference. Must be a reference object -- that
is, an environment or external pointer.}
\item{value}{The value for the weak reference. This can be \code{NULL}, if you
want to use the weak reference like a weak pointer.}
\item{finalizer}{A function that is run after the key becomes unreachable.}
\item{on_quit}{Should the finalizer be run when R exits?}
}
\description{
A weak reference is a special R object which makes it possible to keep a
reference to an object without preventing garbage collection of that object.
It can also be used to keep data about an object without preventing GC of the
object, similar to WeakMaps in JavaScript.
Objects in R are considered \emph{reachable} if they can be accessed by following
a chain of references, starting from a \emph{root node}; root nodes are
specially-designated R objects, and include the global environment and base
environment. As long as the key is reachable, the value will not be garbage
collected. This is true even if the weak reference object becomes
unreachable. The key effectively prevents the weak reference and its value
from being collected, according to the following chain of ownership:
\code{weakref <- key -> value}.
When the key becomes unreachable, the key and value in the weak reference
object are replaced by \code{NULL}, and the finalizer is scheduled to execute.
}
\examples{
e <- env()
# Create a weak reference to e
w <- new_weakref(e, finalizer = function(e) message("finalized"))
# Get the key object from the weak reference
identical(wref_key(w), e)
# When the regular reference (the `e` binding) is removed and a GC occurs,
# the weak reference will not keep the object alive.
rm(e)
gc()
identical(wref_key(w), NULL)
# A weak reference with a key and value. The value contains data about the
# key.
k <- env()
v <- list(1, 2, 3)
w <- new_weakref(k, v)
identical(wref_key(w), k)
identical(wref_value(w), v)
# When v is removed, the weak ref keeps it alive because k is still reachable.
rm(v)
gc()
identical(wref_value(w), list(1, 2, 3))
# When k is removed, the weak ref does not keep k or v alive.
rm(k)
gc()
identical(wref_key(w), NULL)
identical(wref_value(w), NULL)
}
\seealso{
\code{\link[=is_weakref]{is_weakref()}}, \code{\link[=wref_key]{wref_key()}} and \code{\link[=wref_value]{wref_value()}}.
}
\keyword{experimental}
rlang/man/faq-options.Rd 0000644 0001762 0000144 00000002135 14127057575 014675 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/faq.R
\name{faq-options}
\alias{faq-options}
\title{Global options for rlang}
\description{
rlang has several options which may be set globally to control
behavior. A brief description of each is given here. If any functions
are referenced, refer to their documentation for additional details.
\itemize{
\item \code{rlang_interactive}: A logical value used by \code{\link[=is_interactive]{is_interactive()}}. This
can be set to \code{TRUE} to test interactive behavior in unit tests,
for example.
\item \code{rlang_backtrace_on_error}: A character string which controls whether
backtraces are displayed with error messages, and the level of
detail they print. See \link{rlang_backtrace_on_error} for the possible option values.
\item \code{rlang_trace_format_srcrefs}: A logical value used to control whether
srcrefs are printed as part of the backtrace.
\item \code{rlang_trace_top_env}: An environment which will be treated as the
top-level environment when printing traces. See \code{\link[=trace_back]{trace_back()}}
for examples.
}
}
rlang/man/catch_cnd.Rd 0000644 0001762 0000144 00000001477 14127057575 014353 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-handlers.R
\name{catch_cnd}
\alias{catch_cnd}
\title{Catch a condition}
\usage{
catch_cnd(expr, classes = "condition")
}
\arguments{
\item{expr}{Expression to be evaluated with a catching condition
handler.}
\item{classes}{A character vector of condition classes to catch. By
default, catches all conditions.}
}
\value{
A condition if any was signalled, \code{NULL} otherwise.
}
\description{
This is a small wrapper around \code{tryCatch()} that captures any
condition signalled while evaluating its argument. It is useful for
situations where you expect a specific condition to be signalled,
for debugging, and for unit testing.
}
\examples{
catch_cnd(10)
catch_cnd(abort("an error"))
catch_cnd(signal("my_condition", message = "a condition"))
}
rlang/man/vector-coercion.Rd 0000644 0001762 0000144 00000010360 14175213516 015525 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{vector-coercion}
\alias{vector-coercion}
\alias{as_logical}
\alias{as_integer}
\alias{as_double}
\alias{as_complex}
\alias{as_character}
\alias{as_list}
\title{Coerce an object to a base type}
\usage{
as_logical(x)
as_integer(x)
as_double(x)
as_complex(x)
as_character(x, encoding = NULL)
as_list(x)
}
\arguments{
\item{x}{An object to coerce to a base type.}
\item{encoding}{If non-null, set an encoding mark. This is only
declarative, no encoding conversion is performed.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#soft-deprecated}{\figure{lifecycle-soft-deprecated.svg}{options: alt='[Soft-deprecated]'}}}{\strong{[Soft-deprecated]}}
These are equivalent to the base functions (e.g. \code{\link[=as.logical]{as.logical()}},
\code{\link[=as.list]{as.list()}}, etc), but perform coercion rather than conversion.
This means they are not generic and will not call S3 conversion
methods. They only attempt to coerce the base type of their
input. In addition, they have stricter implicit coercion rules and
will never attempt any kind of parsing. E.g. they will not try to
figure out if a character vector represents integers or booleans.
Finally, they treat attributes consistently, unlike the base R
functions: all attributes except names are removed.
}
\section{Lifecycle}{
These functions are deprecated in favour of \code{vctrs::vec_cast()}.
}
\section{Coercion to logical and numeric atomic vectors}{
\itemize{
\item To logical vectors: Integer and integerish double vectors. See
\code{\link[=is_integerish]{is_integerish()}}.
\item To integer vectors: Logical and integerish double vectors.
\item To double vectors: Logical and integer vectors.
\item To complex vectors: Logical, integer and double vectors.
}
}
\section{Coercion to character vectors}{
\code{as_character()} and \code{as_string()} have an optional \code{encoding}
argument to specify the encoding. R uses this information for
internal handling of strings and character vectors. Note that this
is only declarative, no encoding conversion is attempted.
Note that only \code{as_string()} can coerce symbols to a scalar
character vector. This makes the code more explicit and adds an
extra type check.
}
\section{Coercion to lists}{
\code{as_list()} only coerces vector and dictionary types (environments
are an example of dictionary type). Unlike \code{\link[base:list]{base::as.list()}},
\code{as_list()} removes all attributes except names.
}
\section{Effects of removing attributes}{
A technical side-effect of removing the attributes of the input is
that the underlying objects has to be copied. This has no
performance implications in the case of lists because this is a
shallow copy: only the list structure is copied, not the contents
(see \code{\link[=duplicate]{duplicate()}}). However, be aware that atomic vectors
containing large amounts of data will have to be copied.
In general, any attribute modification creates a copy, which is why
it is better to avoid using attributes with heavy atomic vectors.
Uncopyable objects like environments and symbols are an exception
to this rule: in this case, attributes modification happens in
place and has side-effects.
}
\examples{
# Coercing atomic vectors removes attributes with both base R and rlang:
x <- structure(TRUE, class = "foo", bar = "baz")
as.logical(x)
# But coercing lists preserves attributes in base R but not rlang:
l <- structure(list(TRUE), class = "foo", bar = "baz")
as.list(l)
as_list(l)
# Implicit conversions are performed in base R but not rlang:
as.logical(l)
\dontrun{
as_logical(l)
}
# Conversion methods are bypassed, making the result of the
# coercion more predictable:
as.list.foo <- function(x) "wrong"
as.list(l)
as_list(l)
# The input is never parsed. E.g. character vectors of numbers are
# not converted to numeric types:
as.integer("33")
\dontrun{
as_integer("33")
}
# With base R tools there is no way to convert an environment to a
# list without either triggering method dispatch, or changing the
# original environment. as_list() makes it easy:
x <- structure(as_environment(mtcars[1:2]), class = "foobar")
as.list.foobar <- function(x) abort("dont call me")
as_list(x)
}
\keyword{internal}
rlang/man/env_print.Rd 0000644 0001762 0000144 00000002131 14127057575 014435 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env.R
\name{env_print}
\alias{env_print}
\title{Pretty-print an environment}
\usage{
env_print(env = caller_env())
}
\arguments{
\item{env}{An environment, or object that can be converted to an
environment by \code{\link[=get_env]{get_env()}}.}
}
\description{
This prints:
\itemize{
\item The \link[=env_label]{label} and the parent label.
\item Whether the environment is \link[=env_lock]{locked}.
\item The bindings in the environment (up to 20 bindings). They are
printed succintly using \code{pillar::type_sum()} (if available,
otherwise uses an internal version of that generic). In addition
\link[=env_bind_lazy]{fancy bindings} (actives and promises) are
indicated as such.
\item Locked bindings get a \verb{[L]} tag
}
Note that printing a package namespace (see \code{\link[=ns_env]{ns_env()}}) with
\code{env_print()} will typically tag function bindings as \verb{}
until they are evaluated the first time. This is because package
functions are lazily-loaded from disk to improve performance when
loading a package.
}
rlang/man/dots_n.Rd 0000644 0001762 0000144 00000000653 14127057575 013726 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dots.R
\name{dots_n}
\alias{dots_n}
\title{How many arguments are currently forwarded in dots?}
\usage{
dots_n(...)
}
\arguments{
\item{...}{Forwarded arguments.}
}
\description{
This returns the number of arguments currently forwarded in \code{...}
as an integer.
}
\examples{
fn <- function(...) dots_n(..., baz)
fn(foo, bar)
}
\keyword{internal}
rlang/man/as_string.Rd 0000644 0001762 0000144 00000003554 14127057575 014434 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sym.R
\name{as_string}
\alias{as_string}
\title{Cast symbol to string}
\usage{
as_string(x)
}
\arguments{
\item{x}{A string or symbol. If a string, the attributes are
removed, if any.}
}
\value{
A character vector of length 1.
}
\description{
\code{as_string()} converts \link[=sym]{symbols} to character strings.
}
\section{Unicode tags}{
Unlike \code{\link[base:name]{base::as.symbol()}} and \code{\link[base:name]{base::as.name()}}, \code{as_string()}
automatically transforms unicode tags such as \code{""} to the
proper UTF-8 character. This is important on Windows because:
\itemize{
\item R on Windows has no UTF-8 support, and uses native encoding instead.
\item The native encodings do not cover all Unicode characters. For
example, Western encodings do not support CKJ characters.
\item When a lossy UTF-8 -> native transformation occurs, uncovered
characters are transformed to an ASCII unicode tag like \code{""}.
\item Symbols are always encoded in native. This means that
transforming the column names of a data frame to symbols might be
a lossy operation.
\item This operation is very common in the tidyverse because of data
masking APIs like dplyr where data frames are transformed to
environments. While the names of a data frame are stored as a
character vector, the bindings of environments are stored as
symbols.
}
Because it reencodes the ASCII unicode tags to their UTF-8
representation, the string -> symbol -> string roundtrip is
more stable with \code{as_string()}.
}
\examples{
# Let's create some symbols:
foo <- quote(foo)
bar <- sym("bar")
# as_string() converts symbols to strings:
foo
as_string(foo)
typeof(bar)
typeof(as_string(bar))
}
\seealso{
\code{\link[=as_name]{as_name()}} for a higher-level variant of \code{as_string()}
that automatically unwraps quosures.
}
rlang/man/is_namespace.Rd 0000644 0001762 0000144 00000000456 14127057575 015070 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-special.R
\name{is_namespace}
\alias{is_namespace}
\title{Is an object a namespace environment?}
\usage{
is_namespace(x)
}
\arguments{
\item{x}{An object to test.}
}
\description{
Is an object a namespace environment?
}
rlang/man/dots_values.Rd 0000644 0001762 0000144 00000004027 14175213516 014757 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dots.R
\name{dots_values}
\alias{dots_values}
\title{Evaluate dots with preliminary splicing}
\usage{
dots_values(
...,
.ignore_empty = c("trailing", "none", "all"),
.preserve_empty = FALSE,
.homonyms = c("keep", "first", "last", "error"),
.check_assign = FALSE
)
}
\arguments{
\item{...}{Arguments to evaluate and process splicing operators.}
\item{.ignore_empty}{Whether to ignore empty arguments. Can be one
of \code{"trailing"}, \code{"none"}, \code{"all"}. If \code{"trailing"}, only the
last argument is ignored if it is empty.}
\item{.preserve_empty}{Whether to preserve the empty arguments that
were not ignored. If \code{TRUE}, empty arguments are stored with
\code{\link[=missing_arg]{missing_arg()}} values. If \code{FALSE} (the default) an error is
thrown when an empty argument is detected.}
\item{.homonyms}{How to treat arguments with the same name. The
default, \code{"keep"}, preserves these arguments. Set \code{.homonyms} to
\code{"first"} to only keep the first occurrences, to \code{"last"} to keep
the last occurrences, and to \code{"error"} to raise an informative
error and indicate what arguments have duplicated names.}
\item{.check_assign}{Whether to check for \verb{<-} calls. When \code{TRUE} a
warning recommends users to use \code{=} if they meant to match a
function parameter or wrap the \verb{<-} call in curly braces otherwise.
This ensures assignments are explicit.}
}
\description{
This is a tool for advanced users. It captures dots, processes
unquoting and splicing operators, and evaluates them. Unlike
\code{\link[=dots_list]{dots_list()}}, it does not flatten spliced objects, instead they
are attributed a \code{spliced} class (see \code{\link[=splice]{splice()}}). You can process
spliced objects manually, perhaps with a custom predicate (see
\code{\link[=flatten_if]{flatten_if()}}).
}
\examples{
dots <- dots_values(!!! list(1, 2), 3)
dots
# Flatten the objects marked as spliced:
flatten_if(dots, is_spliced)
}
\keyword{internal}
rlang/man/local_error_call.Rd 0000644 0001762 0000144 00000011210 14175213516 015715 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-abort.R
\name{local_error_call}
\alias{local_error_call}
\title{Set local error call in an execution environment}
\usage{
local_error_call(call, frame = caller_env())
}
\arguments{
\item{call}{This can be:
\itemize{
\item A call to be used as context for an error thrown in that
execution environment.
\item The \code{NULL} value to show no context.
\item An execution environment, e.g. as returned by \code{\link[=caller_env]{caller_env()}}.
The \code{\link[=sys.call]{sys.call()}} for that environment is taken as context.
}}
\item{frame}{The execution environment in which to set the local
error call.}
}
\description{
\code{local_error_call()} is an alternative to explicitly passing a
\code{call} argument to \code{\link[=abort]{abort()}}. It sets the call (or a value that
indicates where to find the call, see below) in a local binding
that is automatically picked up by \code{\link[=abort]{abort()}}.
}
\section{Motivation for setting local error calls}{
By default \code{\link[=abort]{abort()}} uses the function call of its caller as
context in error messages:\preformatted{foo <- function() abort("Uh oh.")
foo()
#> Error in `foo()`: Uh oh.
}
This is not always appropriate. For example a function that checks
an input on the behalf of another function should reference the
latter, not the former:\preformatted{arg_check <- function(arg,
error_arg = as_string(substitute(arg))) \{
abort(cli::format_error("\{.arg \{error_arg\}\} is failing."))
\}
foo <- function(x) arg_check(x)
foo()
#> Error in `arg_check()`: `x` is failing.
}
The mismatch is clear in the example above. \code{arg_check()} does not
have any \code{x} argument and so it is confusing to present
\code{arg_check()} as being the relevant context for the failure of the
\code{x} argument.
One way around this is to take a \code{call} or \code{error_call} argument
and pass it to \code{abort()}. Here we name this argument \code{error_call}
for consistency with \code{error_arg} which is prefixed because there is
an existing \code{arg} argument. In other situations, taking \code{arg} and
\code{call} arguments might be appropriate.\preformatted{arg_check <- function(arg,
error_arg = as_string(substitute(arg)),
error_call = caller_env()) \{
abort(
cli::format_error("\{.arg \{error_arg\}\} is failing."),
call = error_call
)
\}
foo <- function(x) arg_check(x)
foo()
#> Error in `foo()`: `x` is failing.
}
This is the generally recommended pattern for argument checking
functions. If you mention an argument in an error message, provide
your callers a way to supply a different argument name and a
different error call. \code{abort()} stores the error call in the \code{call}
condition field which is then used to generate the "in" part of
error messages.
In more complex cases it's often burdensome to pass the relevant
call around, for instance if your checking and throwing code is
structured into many different functions. In this case, use
\code{local_error_call()} to set the call locally or instruct \code{abort()}
to climb the call stack one level to find the relevant call. In the
following example, the complexity is not so important that sparing
the argument passing makes a big difference. However this
illustrates the pattern:\preformatted{arg_check <- function(arg,
error_arg = caller_arg(arg),
error_call = caller_env()) \{
# Set the local error call
local_error_call(error_call)
my_classed_stop(
cli::format_error("\{.arg \{error_arg\}\} is failing.")
)
\}
my_classed_stop <- function(message) \{
# Forward the local error call to the caller's
local_error_call(caller_env())
abort(message, class = "my_class")
\}
foo <- function(x) arg_check(x)
foo()
#> Error in `foo()`: `x` is failing.
}
}
\section{Error call flags in performance-critical functions}{
The \code{call} argument can also be the string \code{"caller"}. This is
equivalent to \code{caller_env()} or \code{parent.frame()} but has a lower
overhead because call stack introspection is only performed when an
error is triggered. Note that eagerly calling \code{caller_env()} is
fast enough in almost all cases.
If your function needs to be really fast, assign the error call
flag directly instead of calling \code{local_error_call()}:\preformatted{.__error_call__. <- "caller"
}
}
\examples{
# Set a context for error messages
function() {
local_error_call(quote(foo()))
local_error_call(sys.call())
}
# Disable the context
function() {
local_error_call(NULL)
}
# Use the caller's context
function() {
local_error_call(caller_env())
}
}
rlang/man/env_names.Rd 0000644 0001762 0000144 00000003254 14127057575 014413 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-binding.R
\name{env_names}
\alias{env_names}
\alias{env_length}
\title{Names and numbers of symbols bound in an environment}
\usage{
env_names(env)
env_length(env)
}
\arguments{
\item{env}{An environment.}
}
\value{
A character vector of object names.
}
\description{
\code{env_names()} returns object names from an enviroment \code{env} as a
character vector. All names are returned, even those starting with
a dot. \code{env_length()} returns the number of bindings.
}
\section{Names of symbols and objects}{
Technically, objects are bound to symbols rather than strings,
since the R interpreter evaluates symbols (see \code{\link[=is_expression]{is_expression()}} for a
discussion of symbolic objects versus literal objects). However it
is often more convenient to work with strings. In rlang
terminology, the string corresponding to a symbol is called the
\emph{name} of the symbol (or by extension the name of an object bound
to a symbol).
}
\section{Encoding}{
There are deep encoding issues when you convert a string to symbol
and vice versa. Symbols are \emph{always} in the native encoding. If
that encoding (let's say latin1) cannot support some characters,
these characters are serialised to ASCII. That's why you sometimes
see strings looking like \verb{}, especially if you're running
Windows (as R doesn't support UTF-8 as native encoding on that
platform).
To alleviate some of the encoding pain, \code{env_names()} always
returns a UTF-8 character vector (which is fine even on Windows)
with ASCII unicode points translated back to UTF-8.
}
\examples{
env <- env(a = 1, b = 2)
env_names(env)
}
rlang/man/missing.Rd 0000644 0001762 0000144 00000004434 14175213516 014102 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vec-na.R
\docType{data}
\name{missing}
\alias{missing}
\alias{na_lgl}
\alias{na_int}
\alias{na_dbl}
\alias{na_chr}
\alias{na_cpl}
\title{Missing values}
\format{
An object of class \code{logical} of length 1.
An object of class \code{integer} of length 1.
An object of class \code{numeric} of length 1.
An object of class \code{character} of length 1.
An object of class \code{complex} of length 1.
}
\usage{
na_lgl
na_int
na_dbl
na_chr
na_cpl
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#questioning}{\figure{lifecycle-questioning.svg}{options: alt='[Questioning]'}}}{\strong{[Questioning]}}
Missing values are represented in R with the general symbol
\code{NA}. They can be inserted in almost all data containers: all
atomic vectors except raw vectors can contain missing values. To
achieve this, R automatically converts the general \code{NA} symbol to a
typed missing value appropriate for the target vector. The objects
provided here are aliases for those typed \code{NA} objects.
}
\details{
Typed missing values are necessary because R needs sentinel values
of the same type (i.e. the same machine representation of the data)
as the containers into which they are inserted. The official typed
missing values are \code{NA_integer_}, \code{NA_real_}, \code{NA_character_} and
\code{NA_complex_}. The missing value for logical vectors is simply the
default \code{NA}. The aliases provided in rlang are consistently named
and thus simpler to remember. Also, \code{na_lgl} is provided as an
alias to \code{NA} that makes intent clearer.
Since \code{na_lgl} is the default \code{NA}, expressions such as \code{c(NA, NA)}
yield logical vectors as no data is available to give a clue of the
target type. In the same way, since lists and environments can
contain any types, expressions like \code{list(NA)} store a logical
\code{NA}.
}
\section{Life cycle}{
These shortcuts might be moved to the vctrs package at some
point. This is why they are marked as questioning.
}
\examples{
typeof(NA)
typeof(na_lgl)
typeof(na_int)
# Note that while the base R missing symbols cannot be overwritten,
# that's not the case for rlang's aliases:
na_dbl <- NA
typeof(na_dbl)
}
\keyword{datasets}
\keyword{internal}
rlang/man/list2.Rd 0000644 0001762 0000144 00000010310 14175213516 013454 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dots.R
\name{list2}
\alias{list2}
\alias{ll}
\alias{dots_list}
\title{Collect dynamic dots in a list}
\usage{
list2(...)
dots_list(
...,
.named = FALSE,
.ignore_empty = c("trailing", "none", "all"),
.preserve_empty = FALSE,
.homonyms = c("keep", "first", "last", "error"),
.check_assign = FALSE
)
}
\arguments{
\item{...}{Arguments to collect in a list. These dots are
\link[=dyn-dots]{dynamic}.}
\item{.named}{If \code{TRUE}, unnamed inputs are automatically named
with \code{\link[=as_label]{as_label()}}. This is equivalent to applying
\code{\link[=exprs_auto_name]{exprs_auto_name()}} on the result. If \code{FALSE}, unnamed elements
are left as is and, if fully unnamed, the list is given minimal
names (a vector of \code{""}). If \code{NULL}, fully unnamed results are
left with \code{NULL} names.}
\item{.ignore_empty}{Whether to ignore empty arguments. Can be one
of \code{"trailing"}, \code{"none"}, \code{"all"}. If \code{"trailing"}, only the
last argument is ignored if it is empty.}
\item{.preserve_empty}{Whether to preserve the empty arguments that
were not ignored. If \code{TRUE}, empty arguments are stored with
\code{\link[=missing_arg]{missing_arg()}} values. If \code{FALSE} (the default) an error is
thrown when an empty argument is detected.}
\item{.homonyms}{How to treat arguments with the same name. The
default, \code{"keep"}, preserves these arguments. Set \code{.homonyms} to
\code{"first"} to only keep the first occurrences, to \code{"last"} to keep
the last occurrences, and to \code{"error"} to raise an informative
error and indicate what arguments have duplicated names.}
\item{.check_assign}{Whether to check for \verb{<-} calls. When \code{TRUE} a
warning recommends users to use \code{=} if they meant to match a
function parameter or wrap the \verb{<-} call in curly braces otherwise.
This ensures assignments are explicit.}
}
\value{
A list containing the \code{...} inputs.
}
\description{
\code{list2(...)} is equivalent to \code{list(...)} with a few additional
features, collectively called \link[=dyn-dots]{dynamic dots}. While
\code{list2()} hard-code these features, \code{dots_list()} is a lower-level
version that offers more control.
}
\examples{
# Let's create a function that takes a variable number of arguments:
numeric <- function(...) {
dots <- list2(...)
num <- as.numeric(dots)
set_names(num, names(dots))
}
numeric(1, 2, 3)
# The main difference with list(...) is that list2(...) enables
# the `!!!` syntax to splice lists:
x <- list(2, 3)
numeric(1, !!! x, 4)
# As well as unquoting of names:
nm <- "yup!"
numeric(!!nm := 1)
# One useful application of splicing is to work around exact and
# partial matching of arguments. Let's create a function taking
# named arguments and dots:
fn <- function(data, ...) {
list2(...)
}
# You normally cannot pass an argument named `data` through the dots
# as it will match `fn`'s `data` argument. The splicing syntax
# provides a workaround:
fn("wrong!", data = letters) # exact matching of `data`
fn("wrong!", dat = letters) # partial matching of `data`
fn(some_data, !!!list(data = letters)) # no matching
# Empty arguments trigger an error by default:
try(fn(, ))
# You can choose to preserve empty arguments instead:
list3 <- function(...) dots_list(..., .preserve_empty = TRUE)
# Note how the last empty argument is still ignored because
# `.ignore_empty` defaults to "trailing":
list3(, )
# The list with preserved empty arguments is equivalent to:
list(missing_arg())
# Arguments with duplicated names are kept by default:
list2(a = 1, a = 2, b = 3, b = 4, 5, 6)
# Use the `.homonyms` argument to keep only the first of these:
dots_list(a = 1, a = 2, b = 3, b = 4, 5, 6, .homonyms = "first")
# Or the last:
dots_list(a = 1, a = 2, b = 3, b = 4, 5, 6, .homonyms = "last")
# Or raise an informative error:
try(dots_list(a = 1, a = 2, b = 3, b = 4, 5, 6, .homonyms = "error"))
# dots_list() can be configured to warn when a `<-` call is
# detected:
my_list <- function(...) dots_list(..., .check_assign = TRUE)
my_list(a <- 1)
# There is no warning if the assignment is wrapped in braces.
# This requires users to be explicit about their intent:
my_list({ a <- 1 })
}
rlang/man/topic-inject-out-of-context.Rd 0000644 0001762 0000144 00000007517 14175213516 017717 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/topic-nse.R
\name{topic-inject-out-of-context}
\alias{topic-inject-out-of-context}
\title{What happens if I use injection operators out of context?}
\description{
The \link[=topic-inject]{injection operators} \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}}, \code{\link[=injection-operator]{!!}}, and \code{\link[=splice-operator]{!!!}} are an extension of the R syntax developed for tidyverse packages. Because they are not part of base R, they suffer from some limitations. In particular no specific error is thrown when they are used in unexpected places.
\subsection{Using \verb{\{\{} out of context}{
The embrace operator \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}} is a feature available in \link[=topic-data-mask]{data-masked} arguments powered by tidy eval. If you use it elsewhere, it is interpreted as a double \verb{\{} wrapping.
In the R language, \verb{\{} is like \code{(} but takes multiple expressions instead of one:\if{html}{\out{
}}
So nothing prevents you from embracing a function argument in a context where this operation is not implemented. R will just treat the braces like a set of parentheses and silently return the result:\if{html}{\out{
}}
This sort of no-effect embracing should be avoided in real code because it falsely suggests that the function supports the tidy eval operator and that something special is happening.
However in many cases embracing is done to implement \link[=topic-data-mask]{data masking}. It is likely that the function will be called with data-variables references which R won't be able to resolve properly:\if{html}{\out{
}}\preformatted{my_mean <- function(data, var) \{
with(data, mean(\{\{ var \}\}))
\}
my_mean(mtcars, cyl)
#> Error in mean(\{: object 'cyl' not found
}\if{html}{\out{
}}
Since \code{\link[=with]{with()}} is a base data-masking function that doesn't support tidy eval operators, the embrace operator does not work and we get an object not found error.
}
\subsection{Using \verb{!!} and \verb{!!!} out of context}{
The injection operators \code{\link{!!}} and \code{\link{!!!}} are implemented in \link[=topic-data-mask]{data-masked} arguments, \link[=dyn-dots]{dynamic dots}, and within \code{\link[=inject]{inject()}}. When used in other contexts, they are interpreted by R as double and triple \emph{negations}.
Double negation can be used in ordinary code to convert an input to logical:\if{html}{\out{
}}
This means that when injection operators are used in the wrong place, they will be interpreted as negation. In the best case scenario you will get a type error:\if{html}{\out{
}}\preformatted{!"foo"
#> Error in !"foo": invalid argument type
!quote(foo)
#> Error in !quote(foo): invalid argument type
!quote(foo())
#> Error in !quote(foo()): invalid argument type
}\if{html}{\out{
}}
In the worst case, R will silently convert the input to logical. Unfortunately there is no systematic way of checking for these errors.
}
}
\keyword{internal}
rlang/man/new_quosure.Rd 0000644 0001762 0000144 00000003573 14175213516 015010 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/quo.R
\name{new_quosure}
\alias{new_quosure}
\alias{as_quosure}
\alias{is_quosure}
\title{Create a quosure from components}
\usage{
new_quosure(expr, env = caller_env())
as_quosure(x, env = NULL)
is_quosure(x)
}
\arguments{
\item{expr}{An expression to wrap in a quosure.}
\item{env}{The environment in which the expression should be
evaluated. Only used for symbols and calls. This should normally
be the environment in which the expression was created.}
\item{x}{An object to test.}
}
\description{
\itemize{
\item \code{new_quosure()} wraps any R object (including expressions,
formulas, or other quosures) into a \link[=topic-quosure]{quosure}.
\item \code{as_quosure()} is similar but it does not rewrap formulas and
quosures.
}
}
\examples{
# `new_quosure()` creates a quosure from its components. These are
# equivalent:
new_quosure(quote(foo), current_env())
quo(foo)
# `new_quosure()` always rewraps its input into a new quosure, even
# if the input is itself a quosure:
new_quosure(quo(foo))
# This is unlike `as_quosure()` which preserves its input if it's
# already a quosure:
as_quosure(quo(foo))
# `as_quosure()` uses the supplied environment with naked expressions:
env <- env(var = "thing")
as_quosure(quote(var), env)
# If the expression already carries an environment, this
# environment is preserved. This is the case for formulas and
# quosures:
as_quosure(~foo, env)
as_quosure(~foo)
# An environment must be supplied when the input is a naked
# expression:
try(
as_quosure(quote(var))
)
}
\seealso{
\itemize{
\item \code{\link[=enquo]{enquo()}} and \code{\link[=quo]{quo()}} for creating a quosure by \link[=topic-defuse]{argument defusal}.
\item \ifelse{html}{\link[=topic-quosure]{What are quosures and when are they needed?}}{\link[=topic-quosure]{What are quosures and when are they needed?}}
}
}
rlang/man/pairlist2.Rd 0000644 0001762 0000144 00000001441 14175213516 014335 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/call.R
\name{pairlist2}
\alias{pairlist2}
\title{Collect dynamic dots in a pairlist}
\usage{
pairlist2(...)
}
\arguments{
\item{...}{<\link[=dyn-dots]{dynamic}> Arguments stored in the
pairlist. Empty arguments are preserved.}
}
\description{
This pairlist constructor uses \link[=dyn-dots]{dynamic dots}. Use
it to manually create argument lists for calls or parameter lists
for functions.
}
\examples{
# Unlike `exprs()`, `pairlist2()` evaluates its arguments.
new_function(pairlist2(x = 1, y = 3 * 6), quote(x * y))
new_function(exprs(x = 1, y = 3 * 6), quote(x * y))
# It preserves missing arguments, which is useful for creating
# parameters without defaults:
new_function(pairlist2(x = , y = 3 * 6), quote(x * y))
}
rlang/man/vector-construction.Rd 0000644 0001762 0000144 00000004115 14175213516 016457 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vec-new.R
\name{vector-construction}
\alias{vector-construction}
\alias{lgl}
\alias{int}
\alias{dbl}
\alias{cpl}
\alias{chr}
\alias{bytes}
\title{Create vectors}
\usage{
lgl(...)
int(...)
dbl(...)
cpl(...)
chr(...)
bytes(...)
}
\arguments{
\item{...}{Components of the new vector. Bare lists and explicitly
spliced lists are spliced.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#questioning}{\figure{lifecycle-questioning.svg}{options: alt='[Questioning]'}}}{\strong{[Questioning]}}
The atomic vector constructors are equivalent to \code{\link[=c]{c()}} but:
\itemize{
\item They allow you to be more explicit about the output
type. Implicit coercions (e.g. from integer to logical) follow
the rules described in \link{vector-coercion}.
\item They use \link[=dyn-dots]{dynamic dots}.
}
}
\section{Life cycle}{
\itemize{
\item All the abbreviated constructors such as \code{lgl()} will probably be
moved to the vctrs package at some point. This is why they are
marked as questioning.
\item Automatic splicing is soft-deprecated and will trigger a warning
in a future version. Please splice explicitly with \verb{!!!}.
}
}
\examples{
# These constructors are like a typed version of c():
c(TRUE, FALSE)
lgl(TRUE, FALSE)
# They follow a restricted set of coercion rules:
int(TRUE, FALSE, 20)
# Lists can be spliced:
dbl(10, !!! list(1, 2L), TRUE)
# They splice names a bit differently than c(). The latter
# automatically composes inner and outer names:
c(a = c(A = 10), b = c(B = 20, C = 30))
# On the other hand, rlang's ctors use the inner names and issue a
# warning to inform the user that the outer names are ignored:
dbl(a = c(A = 10), b = c(B = 20, C = 30))
dbl(a = c(1, 2))
# As an exception, it is allowed to provide an outer name when the
# inner vector is an unnamed scalar atomic:
dbl(a = 1)
# Spliced lists behave the same way:
dbl(!!! list(a = 1))
dbl(!!! list(a = c(A = 1)))
# bytes() accepts integerish inputs
bytes(1:10)
bytes(0x01, 0xff, c(0x03, 0x05), list(10, 20, 30L))
}
rlang/man/quo_label.Rd 0000644 0001762 0000144 00000005455 14175213516 014400 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/quo.R
\name{quo_label}
\alias{quo_label}
\alias{quo_text}
\alias{quo_name}
\title{Format quosures for printing or labelling}
\usage{
quo_label(quo)
quo_text(quo, width = 60L, nlines = Inf)
quo_name(quo)
}
\arguments{
\item{quo}{A quosure or expression.}
\item{width}{Width of each line.}
\item{nlines}{Maximum number of lines to extract.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#questioning}{\figure{lifecycle-questioning.svg}{options: alt='[Questioning]'}}}{\strong{[Questioning]}}
\strong{Note:} You should now use \code{\link[=as_label]{as_label()}} or \code{\link[=as_name]{as_name()}} instead
of \code{quo_name()}. See life cycle section below.
These functions take an arbitrary R object, typically an
\link[=is_expression]{expression}, and represent it as a string.
\itemize{
\item \code{quo_name()} returns an abbreviated representation of the object
as a single line string. It is suitable for default names.
\item \code{quo_text()} returns a multiline string. For instance block
expressions like \code{{ foo; bar }} are represented on 4 lines (one
for each symbol, and the curly braces on their own lines).
}
These deparsers are only suitable for creating default names or
printing output at the console. The behaviour of your functions
should not depend on deparsed objects. If you are looking for a way
of transforming symbols to strings, use \code{\link[=as_string]{as_string()}} instead of
\code{quo_name()}. Unlike deparsing, the transformation between symbols
and strings is non-lossy and well defined.
}
\section{Life cycle}{
These functions are in the questioning life cycle stage.
\itemize{
\item \code{\link[=as_label]{as_label()}} and \code{\link[=as_name]{as_name()}} should be used instead of
\code{quo_name()}. \code{as_label()} transforms any R object to a string
but should only be used to create a default name. Labelisation is
not a well defined operation and no assumption should be made
about the label. On the other hand, \code{as_name()} only works with
(possibly quosured) symbols, but is a well defined and
deterministic operation.
\item We don't have a good replacement for \code{quo_text()} yet. See
\url{https://github.com/r-lib/rlang/issues/636} to follow discussions
about a new deparsing API.
}
}
\examples{
# Quosures can contain nested quosures:
quo <- quo(foo(!! quo(bar)))
quo
# quo_squash() unwraps all quosures and returns a raw expression:
quo_squash(quo)
# This is used by quo_text() and quo_label():
quo_text(quo)
# Compare to the unwrapped expression:
expr_text(quo)
# quo_name() is helpful when you need really short labels:
quo_name(quo(sym))
quo_name(quo(!! sym))
}
\seealso{
\code{\link[=expr_label]{expr_label()}}, \code{\link[=f_label]{f_label()}}
}
\keyword{internal}
rlang/man/embrace-operator.Rd 0000644 0001762 0000144 00000002474 14175213516 015662 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nse-defuse.R
\name{embrace-operator}
\alias{embrace-operator}
\alias{curly-curly}
\title{Embrace operator \verb{\{\{}}
\description{
The embrace operator \verb{\{\{} is used to create functions that call
other \link[=topic-data-mask]{data-masking} functions. It transports a
data-masked argument (an argument that can refer to columns of a
data frame) from one function to another.\if{html}{\out{
}}\preformatted{my_mean <- function(data, var) \{
dplyr::summarise(data, mean = mean(\{\{ var \}\}))
\}
}\if{html}{\out{
}}
}
\section{Under the hood}{
\verb{\{\{} combines \code{\link[=enquo]{enquo()}} and \code{\link[=injection-operator]{!!}} in one
step. The snippet above is equivalent to:\if{html}{\out{
}}\preformatted{my_mean <- function(data, var) \{
var <- enquo(var)
dplyr::summarise(data, mean = mean(!!var))
\}
}\if{html}{\out{
}}
}
\seealso{
\itemize{
\item \ifelse{html}{\link[=topic-data-mask]{What is data-masking and why do I need \{\{?}}{\link[=topic-data-mask]{What is data-masking and why do I need curly-curly?}}
\item \ifelse{html}{\link[=topic-data-mask-programming]{Data mask programming patterns}}{\link[=topic-data-mask-programming]{Data mask programming patterns}}
}
}
rlang/man/has_length.Rd 0000644 0001762 0000144 00000001361 14127057575 014551 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/attr.R
\name{has_length}
\alias{has_length}
\title{How long is an object?}
\usage{
has_length(x, n = NULL)
}
\arguments{
\item{x}{A R object.}
\item{n}{A specific length to test \code{x} with. If \code{NULL},
\code{has_length()} returns \code{TRUE} if \code{x} has length greater than
zero, and \code{FALSE} otherwise.}
}
\description{
This is a function for the common task of testing the length of an
object. It checks the length of an object in a non-generic way:
\code{\link[base:length]{base::length()}} methods are ignored.
}
\examples{
has_length(list())
has_length(list(), 0)
has_length(letters)
has_length(letters, 20)
has_length(letters, 26)
}
\keyword{internal}
rlang/man/topic-embrace-non-args.Rd 0000644 0001762 0000144 00000003132 14175213516 016657 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/topic-nse.R
\name{topic-embrace-non-args}
\alias{topic-embrace-non-args}
\title{Does \verb{\{\{} work on regular objects?}
\description{
The embrace operator \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}} should be used exclusively with function arguments:\if{html}{\out{
}}
In that case, \verb{\{\{} captures the \emph{value} of the expression instead of a defused expression. That's because only function arguments can be defused.
Note that this issue also applies to \code{\link[=enquo]{enquo()}} (on which \verb{\{\{} is based).
}
\section{Why is this not an error?}{
Ideally we would have made \verb{\{\{} on regular objects an error. However this is not possible because in compiled R code it is not always possible to distinguish a regular variable from a function argument. See \ifelse{html}{\link[=topic-embrace-constants]{Why are strings and other constants enquosed in the empty environment?}}{\link[=topic-embrace-constants]{Why are strings and other constants enquosed in the empty environment?}} for more about this.
}
\keyword{internal}
rlang/man/wref_key.Rd 0000644 0001762 0000144 00000000663 14127057575 014254 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/weakref.R
\name{wref_key}
\alias{wref_key}
\alias{wref_value}
\title{Get key/value from a weak reference object}
\usage{
wref_key(x)
wref_value(x)
}
\arguments{
\item{x}{A weak reference object.}
}
\description{
Get key/value from a weak reference object
}
\seealso{
\code{\link[=is_weakref]{is_weakref()}} and \code{\link[=new_weakref]{new_weakref()}}.
}
rlang/man/bare-type-predicates.Rd 0000644 0001762 0000144 00000003033 14175213516 016434 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/types.R
\name{bare-type-predicates}
\alias{bare-type-predicates}
\alias{is_bare_list}
\alias{is_bare_atomic}
\alias{is_bare_vector}
\alias{is_bare_double}
\alias{is_bare_complex}
\alias{is_bare_integer}
\alias{is_bare_numeric}
\alias{is_bare_character}
\alias{is_bare_logical}
\alias{is_bare_raw}
\alias{is_bare_string}
\alias{is_bare_bytes}
\title{Bare type predicates}
\usage{
is_bare_list(x, n = NULL)
is_bare_atomic(x, n = NULL)
is_bare_vector(x, n = NULL)
is_bare_double(x, n = NULL)
is_bare_complex(x, n = NULL)
is_bare_integer(x, n = NULL)
is_bare_numeric(x, n = NULL)
is_bare_character(x, n = NULL)
is_bare_logical(x, n = NULL)
is_bare_raw(x, n = NULL)
is_bare_string(x, n = NULL)
is_bare_bytes(x, n = NULL)
}
\arguments{
\item{x}{Object to be tested.}
\item{n}{Expected length of a vector.}
}
\description{
These predicates check for a given type but only return \code{TRUE} for
bare R objects. Bare objects have no class attributes. For example,
a data frame is a list, but not a bare list.
}
\details{
\itemize{
\item The predicates for vectors include the \code{n} argument for
pattern-matching on the vector length.
\item Like \code{\link[=is_atomic]{is_atomic()}} and unlike base R \code{is.atomic()},
\code{is_bare_atomic()} does not return \code{TRUE} for \code{NULL}.
\item Unlike base R \code{is.numeric()}, \code{is_bare_double()} only returns
\code{TRUE} for floating point numbers.
}
}
\seealso{
\link{type-predicates}, \link{scalar-type-predicates}
}
rlang/man/interrupt.Rd 0000644 0001762 0000144 00000000607 14175213516 014463 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-signal.R
\name{interrupt}
\alias{interrupt}
\title{Simulate interrupt condition}
\usage{
interrupt()
}
\description{
\code{interrupt()} simulates a user interrupt of the kind that is
signalled with \code{Ctrl-C}. It is currently not possible to create
custom interrupt condition objects.
}
\keyword{internal}
rlang/man/as_box.Rd 0000644 0001762 0000144 00000001477 14127057575 013720 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/s3.R
\name{as_box}
\alias{as_box}
\alias{as_box_if}
\title{Convert object to a box}
\usage{
as_box(x, class = NULL)
as_box_if(.x, .p, .class = NULL, ...)
}
\arguments{
\item{x}{An R object.}
\item{class, .class}{A box class. If the input is already a box of
that class, it is returned as is. If the input needs to be boxed,
\code{class} is passed to \code{\link[=new_box]{new_box()}}.}
\item{.x}{An R object.}
\item{.p}{A predicate function.}
\item{...}{Arguments passed to \code{.p}.}
}
\description{
\itemize{
\item \code{as_box()} boxes its input only if it is not already a box. The
class is also checked if supplied.
\item \code{as_box_if()} boxes its input only if it not already a box, or if
the predicate \code{.p} returns \code{TRUE}.
}
}
rlang/man/inherits_any.Rd 0000644 0001762 0000144 00000003042 14127057575 015127 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/s3.R
\name{inherits_any}
\alias{inherits_any}
\alias{inherits_all}
\alias{inherits_only}
\title{Does an object inherit from a set of classes?}
\usage{
inherits_any(x, class)
inherits_all(x, class)
inherits_only(x, class)
}
\arguments{
\item{x}{An object to test for inheritance.}
\item{class}{A character vector of classes.}
}
\description{
\itemize{
\item \code{inherits_any()} is like \code{\link[base:class]{base::inherits()}} but is more explicit
about its behaviour with multiple classes. If \code{classes} contains
several elements and the object inherits from at least one of
them, \code{inherits_any()} returns \code{TRUE}.
\item \code{inherits_all()} tests that an object inherits from all of the
classes in the supplied order. This is usually the best way to
test for inheritance of multiple classes.
\item \code{inherits_only()} tests that the class vectors are identical. It
is a shortcut for \code{identical(class(x), class)}.
}
}
\examples{
obj <- structure(list(), class = c("foo", "bar", "baz"))
# With the _any variant only one class must match:
inherits_any(obj, c("foobar", "bazbaz"))
inherits_any(obj, c("foo", "bazbaz"))
# With the _all variant all classes must match:
inherits_all(obj, c("foo", "bazbaz"))
inherits_all(obj, c("foo", "baz"))
# The order of classes must match as well:
inherits_all(obj, c("baz", "foo"))
# inherits_only() checks that the class vectors are identical:
inherits_only(obj, c("foo", "baz"))
inherits_only(obj, c("foo", "bar", "baz"))
}
rlang/man/env_lock.Rd 0000644 0001762 0000144 00000002763 14175213516 014234 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env.R
\name{env_lock}
\alias{env_lock}
\alias{env_is_locked}
\title{Lock an environment}
\usage{
env_lock(env)
env_is_locked(env)
}
\arguments{
\item{env}{An environment.}
}
\value{
The old value of \code{env_is_locked()} invisibly.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
Locked environments cannot be modified. An important example is
namespace environments which are locked by R when loaded in a
session. Once an environment is locked it normally cannot be
unlocked.
Note that only the environment as a container is locked, not the
individual bindings. You can't remove or add a binding but you can
still modify the values of existing bindings. See
\code{\link[=env_binding_lock]{env_binding_lock()}} for locking individual bindings.
}
\examples{
# New environments are unlocked by default:
env <- env(a = 1)
env_is_locked(env)
# Use env_lock() to lock them:
env_lock(env)
env_is_locked(env)
# Now that `env` is locked, it is no longer possible to remove or
# add bindings. If run, the following would fail:
# env_unbind(env, "a")
# env_bind(env, b = 2)
# Note that even though the environment as a container is locked,
# the individual bindings are still unlocked and can be modified:
env$a <- 10
}
\seealso{
\code{\link[=env_binding_lock]{env_binding_lock()}}
}
\keyword{internal}
rlang/man/env_clone.Rd 0000644 0001762 0000144 00000001125 14175213516 014373 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env.R
\name{env_clone}
\alias{env_clone}
\title{Clone an environment}
\usage{
env_clone(env, parent = env_parent(env))
}
\arguments{
\item{env}{An environment.}
\item{parent}{The parent of the cloned environment.}
}
\description{
This creates a new environment containing exactly the same objects,
optionally with a new parent. Active bindings and promises are
preserved (the latter only on R >= 4.0.0).
}
\examples{
env <- env(!!! mtcars)
clone <- env_clone(env)
identical(env, clone)
identical(env$cyl, clone$cyl)
}
rlang/man/with_env.Rd 0000644 0001762 0000144 00000004057 14175213516 014255 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{with_env}
\alias{with_env}
\alias{locally}
\title{Evaluate an expression within a given environment}
\usage{
with_env(env, expr)
locally(expr)
}
\arguments{
\item{env}{An environment within which to evaluate \code{expr}. Can be
an object with a \code{\link[=get_env]{get_env()}} method.}
\item{expr}{An expression to evaluate.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
These functions evaluate \code{expr} within a given environment (\code{env}
for \code{with_env()}, or the child of the current environment for
\code{locally}). They rely on \code{\link[=eval_bare]{eval_bare()}} which features a lighter
evaluation mechanism than base R \code{\link[base:eval]{base::eval()}}, and which also has
some subtle implications when evaluting stack sensitive functions
(see help for \code{\link[=eval_bare]{eval_bare()}}).
\code{locally()} is equivalent to the base function
\code{\link[base:eval]{base::local()}} but it produces a much cleaner
evaluation stack, and has stack-consistent semantics. It is thus
more suited for experimenting with the R language.
}
\examples{
# with_env() is handy to create formulas with a given environment:
env <- child_env("rlang")
f <- with_env(env, ~new_formula())
identical(f_env(f), env)
# Or functions with a given enclosure:
fn <- with_env(env, function() NULL)
identical(get_env(fn), env)
# Unlike eval() it doesn't create duplicates on the evaluation
# stack. You can thus use it e.g. to create non-local returns:
fn <- function() {
g(current_env())
"normal return"
}
g <- function(env) {
with_env(env, return("early return"))
}
fn()
# Since env is passed to as_environment(), it can be any object with an
# as_environment() method. For strings, the pkg_env() is returned:
with_env("base", ~mtcars)
# This can be handy to put dictionaries in scope:
with_env(mtcars, cyl)
}
\keyword{internal}
rlang/man/caller_arg.Rd 0000644 0001762 0000144 00000002137 14175213516 014522 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-abort.R
\name{caller_arg}
\alias{caller_arg}
\title{Find the caller argument for error messages}
\arguments{
\item{arg}{An argument name in the current function.}
}
\description{
\code{caller_arg()} is a variant of \code{substitute()} or \code{\link[=ensym]{ensym()}} for
arguments that reference other arguments. Unlike \code{substitute()}
which returns an expression, \code{caller_arg()} formats the expression
as a single line string which can be included in error messages.
\itemize{
\item When included in an error message, the resulting label should
generally be formatted as argument, for instance using the \code{.arg}
in the cli package.
\item Use \verb{@inheritParams rlang::args_error_context} to document an
\code{arg} or \code{error_arg} argument that takes \code{error_arg()} as default.
}
}
\examples{
arg_checker <- function(x, arg = caller_arg(x), call = caller_env()) {
cli::cli_abort("{.arg arg} must be a thingy.", call = call)
}
my_function <- function(my_arg) {
arg_checker(my_arg)
}
try(my_function(NULL))
}
rlang/man/check_exclusive.Rd 0000644 0001762 0000144 00000003176 14175213516 015577 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/arg.R
\name{check_exclusive}
\alias{check_exclusive}
\title{Check that arguments are mutually exclusive}
\usage{
check_exclusive(
...,
.require = TRUE,
.frame = caller_env(),
.error_call = .frame
)
}
\arguments{
\item{...}{Function arguments.}
\item{.require}{Whether at least one argument must be supplied.}
\item{.frame}{Environment where the arguments in \code{...} are defined.}
\item{.error_call}{The execution environment of a currently
running function, e.g. \code{caller_env()}. The function will be
mentioned in error messages as the source of the error. See the
\code{call} argument of \code{\link[=abort]{abort()}} for more information.}
}
\value{
The supplied argument name as a string. If \code{.require} is
\code{FALSE} and no argument is supplied, the empty string \code{""} is
returned.
}
\description{
\code{check_exclusive()} checks that only one argument is supplied out of
a set of mutually exclusive arguments. An informative error is
thrown if multiple arguments are supplied.
}
\examples{
f <- function(x, y) {
switch(
check_exclusive(x, y),
x = message("`x` was supplied."),
y = message("`y` was supplied.")
)
}
# Supplying zero or multiple arguments is forbidden
try(f())
try(f(NULL, NULL))
# The user must supply one of the mutually exclusive arguments
f(NULL)
f(y = NULL)
# With `.require` you can allow zero arguments
f <- function(x, y) {
switch(
check_exclusive(x, y, .require = FALSE),
x = message("`x` was supplied."),
y = message("`y` was supplied."),
message("No arguments were supplied")
)
}
f()
}
rlang/man/type_of.Rd 0000644 0001762 0000144 00000003214 14175213516 014071 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{type_of}
\alias{type_of}
\title{Base type of an object}
\usage{
type_of(x)
}
\arguments{
\item{x}{An R object.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#soft-deprecated}{\figure{lifecycle-soft-deprecated.svg}{options: alt='[Soft-deprecated]'}}}{\strong{[Soft-deprecated]}}
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
This is equivalent to \code{\link[base:typeof]{base::typeof()}} with a few differences that
make dispatching easier:
\itemize{
\item The type of one-sided formulas is "quote".
\item The type of character vectors of length 1 is "string".
\item The type of special and builtin functions is "primitive".
}
}
\examples{
type_of(10L)
# Quosures are treated as a new base type but not formulas:
type_of(quo(10L))
type_of(~10L)
# Compare to base::typeof():
typeof(quo(10L))
# Strings are treated as a new base type:
type_of(letters)
type_of(letters[[1]])
# This is a bit inconsistent with the core language tenet that data
# types are vectors. However, treating strings as a different
# scalar type is quite helpful for switching on function inputs
# since so many arguments expect strings:
switch_type("foo", character = abort("vector!"), string = "result")
# Special and builtin primitives are both treated as primitives.
# That's because it is often irrelevant which type of primitive an
# input is:
typeof(list)
typeof(`$`)
type_of(list)
type_of(`$`)
}
\keyword{internal}
rlang/man/type-predicates.Rd 0000644 0001762 0000144 00000003232 14175213516 015526 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/types.R
\name{type-predicates}
\alias{type-predicates}
\alias{is_list}
\alias{is_atomic}
\alias{is_vector}
\alias{is_integer}
\alias{is_double}
\alias{is_complex}
\alias{is_character}
\alias{is_logical}
\alias{is_raw}
\alias{is_bytes}
\alias{is_null}
\title{Type predicates}
\usage{
is_list(x, n = NULL)
is_atomic(x, n = NULL)
is_vector(x, n = NULL)
is_integer(x, n = NULL)
is_double(x, n = NULL, finite = NULL)
is_complex(x, n = NULL, finite = NULL)
is_character(x, n = NULL)
is_logical(x, n = NULL)
is_raw(x, n = NULL)
is_bytes(x, n = NULL)
is_null(x)
}
\arguments{
\item{x}{Object to be tested.}
\item{n}{Expected length of a vector.}
\item{finite}{Whether all values of the vector are finite. The
non-finite values are \code{NA}, \code{Inf}, \code{-Inf} and \code{NaN}. Setting this
to something other than \code{NULL} can be expensive because the whole
vector needs to be traversed and checked.}
}
\description{
These type predicates aim to make type testing in R more
consistent. They are wrappers around \code{\link[base:typeof]{base::typeof()}}, so operate
at a level beneath S3/S4 etc.
}
\details{
Compared to base R functions:
\itemize{
\item The predicates for vectors include the \code{n} argument for
pattern-matching on the vector length.
\item Unlike \code{is.atomic()}, \code{is_atomic()} does not return \code{TRUE} for
\code{NULL}.
\item Unlike \code{is.vector()}, \code{is_vector()} tests if an object is an
atomic vector or a list. \code{is.vector} checks for the presence of
attributes (other than name).
}
}
\seealso{
\link{bare-type-predicates} \link{scalar-type-predicates}
}
rlang/man/as_function.Rd 0000644 0001762 0000144 00000003666 14175213516 014747 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fn.R
\name{as_function}
\alias{as_function}
\alias{is_lambda}
\title{Convert to function}
\usage{
as_function(
x,
env = global_env(),
...,
arg = caller_arg(x),
call = caller_env()
)
is_lambda(x)
}
\arguments{
\item{x}{A function or formula.
If a \strong{function}, it is used as is.
If a \strong{formula}, e.g. \code{~ .x + 2}, it is converted to a function
with up to two arguments: \code{.x} (single argument) or \code{.x} and \code{.y}
(two arguments). The \code{.} placeholder can be used instead of \code{.x}.
This allows you to create very compact anonymous functions (lambdas) with up
to two inputs. Functions created from formulas have a special
class. Use \code{is_lambda()} to test for it.
If a \strong{string}, the function is looked up in \code{env}. Note that
this interface is strictly for user convenience because of the
scoping issues involved. Package developers should avoid
supplying functions by name and instead supply them by value.}
\item{env}{Environment in which to fetch the function in case \code{x}
is a string.}
\item{...}{These dots are for future extensions and must be empty.}
\item{arg}{An argument name as a string. This argument
will be mentioned in error messages as the input that is at the
origin of a problem.}
\item{call}{The execution environment of a currently
running function, e.g. \code{caller_env()}. The function will be
mentioned in error messages as the source of the error. See the
\code{call} argument of \code{\link[=abort]{abort()}} for more information.}
}
\description{
\code{as_function()} transforms a one-sided formula into a function.
This powers the lambda syntax in packages like purrr.
}
\examples{
f <- as_function(~ .x + 1)
f(10)
g <- as_function(~ -1 * .)
g(4)
h <- as_function(~ .x - .y)
h(6, 3)
# Functions created from a formula have a special class:
is_lambda(f)
is_lambda(as_function(function() "foo"))
}
rlang/man/trace_back.Rd 0000644 0001762 0000144 00000006752 14175213516 014514 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/trace.R
\name{trace_back}
\alias{trace_back}
\alias{trace_length}
\title{Capture a backtrace}
\usage{
trace_back(top = NULL, bottom = NULL)
trace_length(trace)
}
\arguments{
\item{top}{The first frame environment to be included in the
backtrace. This becomes the top of the backtrace tree and
represents the oldest call in the backtrace.
This is needed in particular when you call \code{trace_back()}
indirectly or from a larger context, for example in tests or
inside an RMarkdown document where you don't want all of the
knitr evaluation mechanisms to appear in the backtrace.
If not supplied, the \code{rlang_trace_top_env} global option is
consulted. This makes it possible to trim the embedding context
for all backtraces created while the option is set. If knitr is
in progress, the default value for this option is
\code{knitr::knit_global()} so that the knitr context is trimmed out
of backtraces.}
\item{bottom}{The last frame environment to be included in the
backtrace. This becomes the rightmost leaf of the backtrace tree
and represents the youngest call in the backtrace.
Set this when you would like to capture a backtrace without the
capture context.
Can also be an integer that will be passed to \code{\link[=caller_env]{caller_env()}}.}
\item{trace}{A backtrace created by \code{trace_back()}.}
}
\description{
A backtrace captures the sequence of calls that lead to the current
function (sometimes called the call stack). Because of lazy
evaluation, the call stack in R is actually a tree, which the
\code{print()} method for this object will reveal.
Users rarely need to call \code{trace_back()} manually. Instead,
signalling an error with \code{\link[=abort]{abort()}} or setting up \code{\link[=global_entrace]{global_entrace()}}
is the most common way to create backtraces when an error is
thrown. Inspect the backtrace created for the most recent error
with \code{\link[=last_error]{last_error()}}.
\code{trace_length()} returns the number of frames in a backtrace.
}
\examples{
# Trim backtraces automatically (this improves the generated
# documentation for the rlang website and the same trick can be
# useful within knitr documents):
options(rlang_trace_top_env = current_env())
f <- function() g()
g <- function() h()
h <- function() trace_back()
# When no lazy evaluation is involved the backtrace is linear
# (i.e. every call has only one child)
f()
# Lazy evaluation introduces a tree like structure
identity(identity(f()))
identity(try(f()))
try(identity(f()))
# When printing, you can request to simplify this tree to only show
# the direct sequence of calls that lead to `trace_back()`
x <- try(identity(f()))
x
print(x, simplify = "branch")
# With a little cunning you can also use it to capture the
# tree from within a base NSE function
x <- NULL
with(mtcars, {x <<- f(); 10})
x
# Restore default top env for next example
options(rlang_trace_top_env = NULL)
# When code is executed indirectly, i.e. via source or within an
# RMarkdown document, you'll tend to get a lot of guff at the beginning
# related to the execution environment:
conn <- textConnection("summary(f())")
source(conn, echo = TRUE, local = TRUE)
close(conn)
# To automatically strip this off, specify which frame should be
# the top of the backtrace. This will automatically trim off calls
# prior to that frame:
top <- current_env()
h <- function() trace_back(top)
conn <- textConnection("summary(f())")
source(conn, echo = TRUE, local = TRUE)
close(conn)
}
rlang/man/call_match.Rd 0000644 0001762 0000144 00000004646 14175213516 014525 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/call.R
\name{call_match}
\alias{call_match}
\title{Match supplied arguments to function definition}
\usage{
call_match(
call = NULL,
fn = NULL,
...,
defaults = FALSE,
dots_env = NULL,
dots_expand = TRUE
)
}
\arguments{
\item{call}{A call. The arguments will be matched to \code{fn}.}
\item{fn}{A function definition to match arguments to.}
\item{...}{These dots must be empty.}
\item{defaults}{Whether to match missing arguments to their
defaults.}
\item{dots_env}{An execution environment where to find dots. If
supplied and dots exist in this environment, and if \code{call}
includes \code{...}, the forwarded dots are matched to numbered dots
(e.g. \code{..1}, \code{..2}, etc). By default this is set to the empty
environment which means that \code{...} expands to nothing.}
\item{dots_expand}{If \code{FALSE}, arguments passed through \code{...} will
not be spliced into \code{call}. Instead, they are gathered in a
pairlist and assigned to an argument named \code{...}. Gathering dots
arguments is useful if you need to separate them from the other
named arguments.
Note that the resulting call is not meant to be evaluated since R
does not support passing dots through a named argument, even if
named \code{"..."}.}
}
\description{
\code{call_match()} is like \code{\link[=match.call]{match.call()}} with these differences:
\itemize{
\item It supports matching missing argument to their defaults in the
function definition.
\item It requires you to be a little more specific in some cases.
Either all arguments are inferred from the call stack or none of
them are (see the Inference section).
}
}
\section{Inference from the call stack}{
When \code{call} is not supplied, it is inferred from the call stack
along with \code{fn} and \code{dots_env}.
\itemize{
\item \code{call} and \code{fn} are inferred from the calling environment:
\code{sys.call(sys.parent())} and \code{sys.function(sys.parent())}.
\item \code{dots_env} is inferred from the caller of the calling
environment: \code{caller_env(2)}.
}
If \code{call} is supplied, then you must supply \code{fn} as well. Also
consider supplying \code{dots_env} as it is set to the empty environment
when not inferred.
}
\examples{
# `call_match()` supports matching missing arguments to their
# defaults
fn <- function(x = "default") fn
call_match(quote(fn()), fn)
call_match(quote(fn()), fn, defaults = TRUE)
}
rlang/man/args_error_context.Rd 0000644 0001762 0000144 00000002416 14175213516 016340 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-abort.R
\name{args_error_context}
\alias{args_error_context}
\title{Documentation anchor for error arguments}
\arguments{
\item{arg, error_arg}{An argument name as a string. This argument
will be mentioned in error messages as the input that is at the
origin of a problem.}
\item{call, error_call}{The execution environment of a currently
running function, e.g. \code{caller_env()}. The function will be
mentioned in error messages as the source of the error. See the
\code{call} argument of \code{\link[=abort]{abort()}} for more information.}
}
\description{
Use \verb{@inheritParams rlang::args_error_context} in your package to
document \code{arg} and \code{call} arguments (or equivalently their prefixed
versions \code{error_arg} and \code{error_call}).
\itemize{
\item \code{arg} parameters should be formatted as argument (e.g. using
cli's \code{.arg} specifier) and included in error messages. See also
\code{\link[=caller_arg]{caller_arg()}}.
\item \code{call} parameters should be included in error conditions in a
field named \code{call}. An easy way to do this is by passing a \code{call}
argument to \code{\link[=abort]{abort()}}. See also \code{\link[=local_error_call]{local_error_call()}}.
}
}
rlang/man/as_utf8_character.Rd 0000644 0001762 0000144 00000003511 14175213516 016011 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utils-encoding.R
\name{as_utf8_character}
\alias{as_utf8_character}
\title{Coerce to a character vector and attempt encoding conversion}
\usage{
as_utf8_character(x)
}
\arguments{
\item{x}{An object to coerce.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
Unlike specifying the \code{encoding} argument in \code{as_string()} and
\code{as_character()}, which is only declarative, these functions
actually attempt to convert the encoding of their input. There are
two possible cases:
\itemize{
\item The string is tagged as UTF-8 or latin1, the only two encodings
for which R has specific support. In this case, converting to the
same encoding is a no-op, and converting to native always works
as expected, as long as the native encoding, the one specified by
the \code{LC_CTYPE} locale has support for all characters occurring in
the strings. Unrepresentable characters are serialised as unicode
points: "".
\item The string is not tagged. R assumes that it is encoded in the
native encoding. Conversion to native is a no-op, and conversion
to UTF-8 should work as long as the string is actually encoded in
the locale codeset.
}
When translating to UTF-8, the strings are parsed for serialised
unicode points (e.g. strings looking like "U+xxxx") with
\code{\link[=chr_unserialise_unicode]{chr_unserialise_unicode()}}. This helps to alleviate the effects of
character-to-symbol-to-character roundtrips on systems with
non-UTF-8 native encoding.
}
\examples{
# Let's create a string marked as UTF-8 (which is guaranteed by the
# Unicode escaping in the string):
utf8 <- "caf\uE9"
Encoding(utf8)
charToRaw(utf8)
}
\keyword{internal}
rlang/man/env_has.Rd 0000644 0001762 0000144 00000001702 14127057575 014057 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-binding.R
\name{env_has}
\alias{env_has}
\title{Does an environment have or see bindings?}
\usage{
env_has(env = caller_env(), nms, inherit = FALSE)
}
\arguments{
\item{env}{An environment.}
\item{nms}{A character vector of binding names for which to check
existence.}
\item{inherit}{Whether to look for bindings in the parent
environments.}
}
\value{
A named logical vector as long as \code{nms}.
}
\description{
\code{env_has()} is a vectorised predicate that queries whether an
environment owns bindings personally (with \code{inherit} set to
\code{FALSE}, the default), or sees them in its own environment or in
any of its parents (with \code{inherit = TRUE}).
}
\examples{
parent <- child_env(NULL, foo = "foo")
env <- child_env(parent, bar = "bar")
# env does not own `foo` but sees it in its parent environment:
env_has(env, "foo")
env_has(env, "foo", inherit = TRUE)
}
rlang/man/topic-embrace-constants.Rd 0000644 0001762 0000144 00000006434 14175213516 017157 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/topic-nse.R
\name{topic-embrace-constants}
\alias{topic-embrace-constants}
\title{Why are strings and other constants enquosed in the empty environment?}
\description{
Function arguments are \link[=topic-defuse]{defused} into \link[=topic-quosure]{quosures} that keep track of the environment of the defused expression.\if{html}{\out{
}}
You might have noticed that when constants are supplied, the quosure tracks the empty environment instead of the current environmnent.\if{html}{\out{
}}
The reason for this has to do with compilation of R code which makes it impossible to consistently capture environments of constants from function arguments. Argument defusing relies on the \emph{promise} mechanism of R for lazy evaluation of arguments. When functions are compiled and R notices that an argument is constant, it avoids creating a promise since they slow down function evaluation. Instead, the function is directly supplied a naked constant instead of constant wrapped in a promise.
}
\section{Concrete case of promise unwrapping by compilation}{
We can observe this optimisation by calling into the C-level \code{findVar()} function to capture promises.\if{html}{\out{
}}\preformatted{# Return the object bound to `arg` without triggering evaluation of
# promises
f <- function(arg) \{
rlang:::find_var(current_env(), sym("arg"))
\}
# Call `f()` with a symbol or with a constant
g <- function(symbolic) \{
if (symbolic) \{
f(letters)
\} else \{
f("foo")
\}
\}
# Make sure these small functions are compiled
f <- compiler::cmpfun(f)
g <- compiler::cmpfun(g)
}\if{html}{\out{
}}
When \code{f()} is called with a symbolic argument, we get the promise object created by R.\if{html}{\out{
}}
Without a promise, there is no way to figure out the original environment of an argument.
}
\section{Do we need environments for constants?}{
Data-masking APIs in the tidyverse are intentionally designed so that they don't need an environment for constants.
\itemize{
\item Data-masking APIs should be able to interpret constants. These can arise from normal argument passing as we have seen, or by \link[=topic-inject]{injection} with \verb{!!}. There should be no difference between \code{dplyr::mutate(mtcars, var = cyl)} and \code{dplyr::mutate(mtcars, var = !!mtcars$cyl)}.
\item Data-masking is an \emph{evaluation} idiom, not an \emph{introspective} one. The behaviour of data-masking function should not depend on the calling environment when a constant (or a symbol evaluating to a given value) is supplied.
}
}
\keyword{internal}
rlang/man/cnd_muffle.Rd 0000644 0001762 0000144 00000005444 14127057575 014545 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-handlers.R
\name{cnd_muffle}
\alias{cnd_muffle}
\title{Muffle a condition}
\usage{
cnd_muffle(cnd)
}
\arguments{
\item{cnd}{A condition to muffle.}
}
\value{
If \code{cnd} is mufflable, \code{cnd_muffle()} jumps to the muffle
restart and doesn't return. Otherwise, it returns \code{FALSE}.
}
\description{
Unlike \code{\link[=exiting]{exiting()}} handlers, \code{\link[=calling]{calling()}} handlers must be explicit
that they have handled a condition to stop it from propagating to
other handlers. Use \code{cnd_muffle()} within a calling handler (or as
a calling handler, see examples) to prevent any other handlers from
being called for that condition.
}
\section{Mufflable conditions}{
Most conditions signalled by base R are muffable, although the name
of the restart varies. cnd_muffle() will automatically call the
correct restart for you. It is compatible with the following
conditions:
\itemize{
\item \code{warning} and \code{message} conditions. In this case \code{cnd_muffle()}
is equivalent to \code{\link[base:message]{base::suppressMessages()}} and
\code{\link[base:warning]{base::suppressWarnings()}}.
\item Bare conditions signalled with \code{signal()} or \code{\link[=cnd_signal]{cnd_signal()}}. Note
that conditions signalled with \code{\link[base:conditions]{base::signalCondition()}} are not
mufflable.
\item Interrupts are sometimes signalled with a \code{resume} restart on
recent R versions. When this is the case, you can muffle the
interrupt with \code{cnd_muffle()}. Check if a restart is available
with \code{base::findRestart("resume")}.
}
If you call \code{cnd_muffle()} with a condition that is not mufflable
you will cause a new error to be signalled.
\itemize{
\item Errors are not mufflable since they are signalled in critical
situations where execution cannot continue safely.
\item Conditions captured with \code{\link[base:conditions]{base::tryCatch()}}, \code{\link[=with_handlers]{with_handlers()}} or
\code{\link[=catch_cnd]{catch_cnd()}} are no longer mufflable. Muffling restarts \emph{must}
be called from a \link{calling} handler.
}
}
\examples{
fn <- function() {
inform("Beware!", "my_particular_msg")
inform("On your guard!")
"foobar"
}
# Let's install a muffling handler for the condition thrown by `fn()`.
# This will suppress all `my_particular_wng` warnings but let other
# types of warnings go through:
with_handlers(fn(),
my_particular_msg = calling(function(cnd) {
inform("Dealt with this particular message")
cnd_muffle(cnd)
})
)
# Note how execution of `fn()` continued normally after dealing
# with that particular message.
# cnd_muffle() can also be passed to with_handlers() as a calling
# handler:
with_handlers(fn(),
my_particular_msg = calling(cnd_muffle)
)
}
\keyword{internal}
rlang/man/call2.Rd 0000644 0001762 0000144 00000006270 14175213516 013426 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/call.R
\name{call2}
\alias{call2}
\title{Create a call}
\usage{
call2(.fn, ..., .ns = NULL)
}
\arguments{
\item{.fn}{Function to call. Must be a callable object: a string,
symbol, call, or a function.}
\item{...}{<\link[=dyn-dots]{dynamic}> Arguments for the function
call. Empty arguments are preserved.}
\item{.ns}{Namespace with which to prefix \code{.fn}. Must be a string
or symbol.}
}
\description{
Quoted function calls are one of the two types of
\link[=is_symbolic]{symbolic} objects in R. They represent the action of
calling a function, possibly with arguments. There are two ways of
creating a quoted call:
\itemize{
\item By \link[=nse-defuse]{quoting} it. Quoting prevents functions from being
called. Instead, you get the description of the function call as
an R object. That is, a quoted function call.
\item By constructing it with \code{\link[base:call]{base::call()}}, \code{\link[base:call]{base::as.call()}}, or
\code{call2()}. In this case, you pass the call elements (the function
to call and the arguments to call it with) separately.
}
See section below for the difference between \code{call2()} and the base
constructors.
}
\section{Difference with base constructors}{
\code{call2()} is more flexible than \code{base::call()}:
\itemize{
\item The function to call can be a string or a \link[=is_callable]{callable}
object: a symbol, another call (e.g. a \code{$} or \code{[[} call), or a
function to inline. \code{base::call()} only supports strings and you
need to use \code{base::as.call()} to construct a call with a callable
object.\preformatted{call2(list, 1, 2)
as.call(list(list, 1, 2))
}
\item The \code{.ns} argument is convenient for creating namespaced calls.\preformatted{call2("list", 1, 2, .ns = "base")
# Equivalent to
ns_call <- call("::", as.symbol("list"), as.symbol("base"))
as.call(list(ns_call, 1, 2))
}
\item \code{call2()} has \link[=list2]{dynamic dots} support. You can splice lists
of arguments with \verb{!!!} or unquote an argument name with glue
syntax.\preformatted{args <- list(na.rm = TRUE, trim = 0)
call2("mean", 1:10, !!!args)
# Equivalent to
as.call(c(list(as.symbol("mean"), 1:10), args))
}
}
}
\section{Caveats of inlining objects in calls}{
\code{call2()} makes it possible to inline objects in calls, both in
function and argument positions. Inlining an object or a function
has the advantage that the correct object is used in all
environments. If all components of the code are inlined, you can
even evaluate in the \link[=empty_env]{empty environment}.
However inlining also has drawbacks. It can cause issues with NSE
functions that expect symbolic arguments. The objects may also leak
in representations of the call stack, such as \code{\link[=traceback]{traceback()}}.
}
\examples{
# fn can either be a string, a symbol or a call
call2("f", a = 1)
call2(quote(f), a = 1)
call2(quote(f()), a = 1)
#' Can supply arguments individually or in a list
call2(quote(f), a = 1, b = 2)
call2(quote(f), !!!list(a = 1, b = 2))
# Creating namespaced calls is easy:
call2("fun", arg = quote(baz), .ns = "mypkg")
# Empty arguments are preserved:
call2("[", quote(x), , drop = )
}
\seealso{
call_modify
}
rlang/man/env.Rd 0000644 0001762 0000144 00000012337 14175213516 013222 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env.R
\name{env}
\alias{env}
\alias{child_env}
\alias{new_environment}
\title{Create a new environment}
\usage{
env(...)
child_env(.parent, ...)
new_environment(data = list(), parent = empty_env())
}
\arguments{
\item{..., data}{<\link[=dyn-dots]{dynamic}> Named values. You can
supply one unnamed to specify a custom parent, otherwise it
defaults to the current environment.}
\item{.parent, parent}{A parent environment.}
}
\description{
These functions create new environments.
\itemize{
\item \code{env()} creates a child of the current environment by default
and takes a variable number of named objects to populate it.
\item \code{new_environment()} creates a child of the empty environment by
default and takes a named list of objects to populate it.
}
}
\section{Environments as objects}{
Environments are containers of uniquely named objects. Their most
common use is to provide a scope for the evaluation of R
expressions. Not all languages have first class environments,
i.e. can manipulate scope as regular objects. Reification of scope
is one of the most powerful features of R as it allows you to change
what objects a function or expression sees when it is evaluated.
Environments also constitute a data structure in their own
right. They are a collection of uniquely named objects, subsettable
by name and modifiable by reference. This latter property (see
section on reference semantics) is especially useful for creating
mutable OO systems (cf the \href{https://github.com/r-lib/R6}{R6 package}
and the \href{https://ggplot2.tidyverse.org/articles/extending-ggplot2.html}{ggproto system}
for extending ggplot2).
}
\section{Inheritance}{
All R environments (except the \link[=empty_env]{empty environment}) are
defined with a parent environment. An environment and its
grandparents thus form a linear hierarchy that is the basis for
\href{https://en.wikipedia.org/wiki/Scope_(computer_science)}{lexical scoping} in
R. When R evaluates an expression, it looks up symbols in a given
environment. If it cannot find these symbols there, it keeps
looking them up in parent environments. This way, objects defined
in child environments have precedence over objects defined in
parent environments.
The ability of overriding specific definitions is used in the
tidyeval framework to create powerful domain-specific grammars. A
common use of masking is to put data frame columns in scope. See
for example \code{\link[=as_data_mask]{as_data_mask()}}.
}
\section{Reference semantics}{
Unlike regular objects such as vectors, environments are an
\link[=is_copyable]{uncopyable} object type. This means that if you
have multiple references to a given environment (by assigning the
environment to another symbol with \verb{<-} or passing the environment
as argument to a function), modifying the bindings of one of those
references changes all other references as well.
}
\section{Life cycle}{
\itemize{
\item \code{child_env()} is in the questioning stage. It is redundant now
that \code{env()} accepts parent environments.
}
}
\examples{
# env() creates a new environment which has the current environment
# as parent
env <- env(a = 1, b = "foo")
env$b
identical(env_parent(env), current_env())
# Supply one unnamed argument to override the default:
env <- env(base_env(), a = 1, b = "foo")
identical(env_parent(env), base_env())
# child_env() lets you specify a parent:
child <- child_env(env, c = "bar")
identical(env_parent(child), env)
# This child environment owns `c` but inherits `a` and `b` from `env`:
env_has(child, c("a", "b", "c", "d"))
env_has(child, c("a", "b", "c", "d"), inherit = TRUE)
# `parent` is passed to as_environment() to provide handy
# shortcuts. Pass a string to create a child of a package
# environment:
child_env("rlang")
env_parent(child_env("rlang"))
# Or `NULL` to create a child of the empty environment:
child_env(NULL)
env_parent(child_env(NULL))
# The base package environment is often a good default choice for a
# parent environment because it contains all standard base
# functions. Also note that it will never inherit from other loaded
# package environments since R keeps the base package at the tail
# of the search path:
base_child <- child_env("base")
env_has(base_child, c("lapply", "("), inherit = TRUE)
# On the other hand, a child of the empty environment doesn't even
# see a definition for `(`
empty_child <- child_env(NULL)
env_has(empty_child, c("lapply", "("), inherit = TRUE)
# Note that all other package environments inherit from base_env()
# as well:
rlang_child <- child_env("rlang")
env_has(rlang_child, "env", inherit = TRUE) # rlang function
env_has(rlang_child, "lapply", inherit = TRUE) # base function
# Both env() and child_env() support tidy dots features:
objs <- list(b = "foo", c = "bar")
env <- env(a = 1, !!! objs)
env$c
# You can also unquote names with the definition operator `:=`
var <- "a"
env <- env(!!var := "A")
env$a
# Use new_environment() to create containers with the empty
# environment as parent:
env <- new_environment()
env_parent(env)
# Like other new_ constructors, it takes an object rather than dots:
new_environment(list(a = "foo", b = "bar"))
}
\seealso{
\code{\link[=env_has]{env_has()}}, \code{\link[=env_bind]{env_bind()}}.
}
rlang/man/quosure-tools.Rd 0000644 0001762 0000144 00000007003 14175213516 015265 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/quo.R
\name{quosure-tools}
\alias{quosure-tools}
\alias{quosure}
\alias{quo_is_missing}
\alias{quo_is_symbol}
\alias{quo_is_call}
\alias{quo_is_symbolic}
\alias{quo_is_null}
\alias{quo_get_expr}
\alias{quo_get_env}
\alias{quo_set_expr}
\alias{quo_set_env}
\title{Quosure getters, setters and predicates}
\usage{
quo_is_missing(quo)
quo_is_symbol(quo, name = NULL)
quo_is_call(quo, name = NULL, n = NULL, ns = NULL)
quo_is_symbolic(quo)
quo_is_null(quo)
quo_get_expr(quo)
quo_get_env(quo)
quo_set_expr(quo, expr)
quo_set_env(quo, env)
}
\arguments{
\item{quo}{A quosure to test.}
\item{name}{The name of the symbol or function call. If \code{NULL} the
name is not tested.}
\item{n}{An optional number of arguments that the call should
match.}
\item{ns}{The namespace of the call. If \code{NULL}, the namespace
doesn't participate in the pattern-matching. If an empty string
\code{""} and \code{x} is a namespaced call, \code{is_call()} returns
\code{FALSE}. If any other string, \code{is_call()} checks that \code{x} is
namespaced within \code{ns}.
Can be a character vector of namespaces, in which case the call
has to match at least one of them, otherwise \code{is_call()} returns
\code{FALSE}.}
\item{expr}{A new expression for the quosure.}
\item{env}{A new environment for the quosure.}
}
\description{
These tools inspect and modify \link[=topic-quosure]{quosures}, a type of
\link[=topic-defuse]{defused expression} that includes a reference to the
context where it was created. A quosure is guaranteed to evaluate
in its original environment and can refer to local objects safely.
\itemize{
\item You can access the quosure components with \code{quo_get_expr()} and
\code{quo_get_env()}.
\item The \code{quo_} prefixed predicates test the expression of a quosure,
\code{quo_is_missing()}, \code{quo_is_symbol()}, etc.
}
All \code{quo_} prefixed functions expect a quosure and will fail if
supplied another type of object. Make sure the input is a quosure
with \code{\link[=is_quosure]{is_quosure()}}.
}
\section{Empty quosures and missing arguments}{
When missing arguments are captured as quosures, either through
\code{\link[=enquo]{enquo()}} or \code{\link[=quos]{quos()}}, they are returned as an empty quosure. These
quosures contain the \link[=missing_arg]{missing argument} and typically
have the \link[=empty_env]{empty environment} as enclosure.
Use \code{quo_is_missing()} to test for a missing argument defused with
\code{\link[=enquo]{enquo()}}.
}
\examples{
quo <- quo(my_quosure)
quo
# Access and set the components of a quosure:
quo_get_expr(quo)
quo_get_env(quo)
quo <- quo_set_expr(quo, quote(baz))
quo <- quo_set_env(quo, empty_env())
quo
# Test wether an object is a quosure:
is_quosure(quo)
# If it is a quosure, you can use the specialised type predicates
# to check what is inside it:
quo_is_symbol(quo)
quo_is_call(quo)
quo_is_null(quo)
# quo_is_missing() checks for a special kind of quosure, the one
# that contains the missing argument:
quo()
quo_is_missing(quo())
fn <- function(arg) enquo(arg)
fn()
quo_is_missing(fn())
}
\seealso{
\itemize{
\item \code{\link[=quo]{quo()}} for creating quosures by \link[=topic-defuse]{argument defusal}.
\item \code{\link[=new_quosure]{new_quosure()}} and \code{\link[=as_quosure]{as_quosure()}} for assembling quosures from
components.
\item \ifelse{html}{\link[=topic-quosure]{What are quosures and when are they needed?}}{\link[=topic-quosure]{What are quosures and when are they needed?}} for an overview.
}
}
rlang/man/missing_arg.Rd 0000644 0001762 0000144 00000013177 14175213516 014737 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/arg.R
\name{missing_arg}
\alias{missing_arg}
\alias{is_missing}
\alias{maybe_missing}
\title{Generate or handle a missing argument}
\usage{
missing_arg()
is_missing(x)
maybe_missing(x, default = missing_arg())
}
\arguments{
\item{x}{An object that might be the missing argument.}
\item{default}{The object to return if the input is missing,
defaults to \code{missing_arg()}.}
}
\description{
These functions help using the missing argument as a regular R
object.
\itemize{
\item \code{missing_arg()} generates a missing argument.
\item \code{is_missing()} is like \code{\link[base:missing]{base::missing()}} but also supports
testing for missing arguments contained in other objects like
lists. It is also more consistent with default arguments which
are never treated as missing (see section below).
\item \code{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.
}
}
\section{Other ways to reify the missing argument}{
\itemize{
\item \code{base::quote(expr = )} is the canonical way to create a missing
argument object.
\item \code{expr()} called without argument creates a missing argument.
\item \code{quo()} called without argument creates an empty quosure, i.e. a
quosure containing the missing argument object.
}
}
\section{\code{is_missing()} and default arguments}{
The base function \code{\link[=missing]{missing()}} makes a distinction between default
values supplied explicitly and default values generated through a
missing argument:\if{html}{\out{
}}\preformatted{## [1] FALSE
}
This only happens within a function. If the default value has been
generated in a calling function, it is never treated as missing:\if{html}{\out{
}}\preformatted{## [1] FALSE
}
\code{rlang::is_missing()} simplifies these rules by never treating
default arguments as missing, even in internal contexts:\if{html}{\out{
}}\preformatted{## [1] FALSE
}
This is a little less flexible because you can't specialise
behaviour based on implicitly supplied default values. However,
this makes the behaviour of \code{is_missing()} and functions using it
simpler to understand.
}
\section{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. For instance, it is possible to bind the missing argument
to a variable with an expression like \code{x[[1]] <- missing_arg()}.
Likewise, \code{x[[1]]} is safe to use as argument, e.g. \code{list(x[[1]])}
even when the result is the missing object.
However, as soon as the missing argument is passed down between
functions through a bare variable, it is likely to cause a missing
argument error:\if{html}{\out{
}}\preformatted{x <- missing_arg()
list(x)
#> Error:
#> ! argument "x" is missing, with no default
}\if{html}{\out{
}}
To work around this, \code{is_missing()} and \code{maybe_missing(x)} use a
bit of magic to determine if the input is the missing argument
without triggering a missing error.\if{html}{\out{
}}\preformatted{rbind(a = 1:2, b = 3:4)
#> [,1] [,2]
#> a 1 2
#> b 3 4
}\if{html}{\out{
}}
But how do you bind a variable number of rows stored in a list? The base R solution is to invoke \code{rbind()} with \code{do.call()}:\if{html}{\out{
}}\preformatted{rows <- list(a = 1:2, b = 3:4)
do.call("rbind", rows)
#> [,1] [,2]
#> a 1 2
#> b 3 4
}\if{html}{\out{
}}
Functions that implement dynamic dots include a built-in way of folding a list of arguments in \code{...}. To illustrate this, we'll create a variant of \code{rbind()} that takes dynamic dots by collecting \code{...} with \code{\link[=list2]{list2()}}:\if{html}{\out{
}}
It can be used just like \code{rbind()}:\if{html}{\out{
}}\preformatted{rbind2(a = 1:2, b = 3:4)
#> [,1] [,2]
#> a 1 2
#> b 3 4
}\if{html}{\out{
}}
And a list of arguments can be supplied by \emph{splicing} the list with \code{\link{!!!}}:\if{html}{\out{
}}\preformatted{rbind2(!!!rows, c = 5:6)
#> [,1] [,2]
#> a 1 2
#> b 3 4
#> c 5 6
}\if{html}{\out{
}}
}
\subsection{Injecting names with \verb{"\{"}}{
A related problem comes up when an argument name is stored in a variable. With dynamic dots, you can inject the name using \href{https://glue.tidyverse.org/}{glue syntax} with \ifelse{html}{\code{\link[=glue-operators]{"\{"}}}{\verb{"\{"}}:\if{html}{\out{
}}\preformatted{name <- "foo"
rbind2("\{name\}" := 1:2, bar = 3:4)
#> [,1] [,2]
#> foo 1 2
#> bar 3 4
rbind2("prefix_\{name\}" := 1:2, bar = 3:4)
#> [,1] [,2]
#> prefix_foo 1 2
#> bar 3 4
}\if{html}{\out{
}}
}
}
\section{Metaprogramming injection}{
\link[=topic-data-mask]{Data-masked} arguments support the following injection operators. They can also be explicitly enabled with \code{\link[=inject]{inject()}}.
\subsection{Embracing with \verb{\{\{}}{
The embracing operator \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}} is made specially for function arguments. It \link[=topic-defuse]{defuses} the expression supplied as argument and immediately injects it in place. The injected argument is then evaluated in another context such as a \link[=topic-data-mask]{data mask}.\if{html}{\out{
}}\preformatted{# Inject function arguments that might contain
# data-variables by embracing them with \{\{ \}\}
mean_by <- function(data, by, var) \{
data \%>\%
dplyr::group_by(\{\{ by \}\}) \%>\%
dplyr::summarise(avg = mean(\{\{ var \}\}, na.rm = TRUE))
\}
# The data-variables `cyl` and `disp` inside the
# env-variables `by` and `var` are injected inside `group_by()`
# and `summarise()`
mtcars \%>\% mean_by(by = cyl, var = disp)
#> # A tibble: 3 x 2
#> cyl avg
#>
#> 1 4 105.
#> 2 6 183.
#> 3 8 353.
}\if{html}{\out{
}}
Learn more about this pattern in \ifelse{html}{\link[=topic-data-mask-programming]{Data mask programming patterns}}{\link[=topic-data-mask-programming]{Data mask programming patterns}}.
}
\subsection{Injecting with \verb{!!}}{
Unlike \code{\link{!!!}} which injects a list of arguments, the injection operator \code{\link{!!}} (pronounced "bang-bang") injects a \emph{single} object. One use case for \verb{!!} is to substitute an environment-variable (created with \verb{<-}) with a data-variable (inside a data frame).\if{html}{\out{
}}\preformatted{# The env-variable `var` contains a data-symbol object, in this
# case a reference to the data-variable `height`
var <- data_sym("disp")
# We inject the data-variable contained in `var` inside `summarise()`
mtcars \%>\%
dplyr::summarise(avg = mean(!!var, na.rm = TRUE))
#> # A tibble: 1 x 1
#> avg
#>
#> 1 231.
}\if{html}{\out{
}}
Another use case is to inject a variable by value to avoid \link[=topic-data-mask-ambiguity]{name collisions}.\if{html}{\out{
}}\preformatted{df <- data.frame(x = 1)
# This name conflicts with a column in `df`
x <- 100
# Inject the env-variable
df \%>\%
dplyr::mutate(x = x / !!x)
#> x
#> 1 0.01
}\if{html}{\out{
}}
Note that in most cases you don't need injection with \verb{!!}. For instance, the \code{\link{.data}} and \code{\link{.env}} pronouns provide more intuitive alternatives to injecting a column name and injecting a value.
}
\subsection{Splicing with \verb{!!!}}{
The splice operator \code{\link{!!!}} of dynamic dots can also be used in metaprogramming context (inside \link[=topic-data-mask]{data-masked} arguments and inside \code{\link[=inject]{inject()}}). For instance, we could reimplement the \code{rbind2()} function presented above using \code{inject()} instead of \code{do.call()}:\if{html}{\out{
}}
There are two things going on here. We collect \code{...} with \code{\link[=list2]{list2()}} so that the callers of \code{rbind2()} may use \verb{!!!}. And we use \code{inject()} so that \code{rbind2()} itself may use \verb{!!!} to splice the list of arguments passed to \code{rbind2()}.
}
}
\section{Injection in other languages}{
Injection is known as \strong{quasiquotation} in other programming languages and in computer science. \code{expr()} is similar to a quasiquotation operator and \verb{!!} is the unquote operator. These terms have a rich history in Lisp languages, and live on in modern languages like \href{https://docs.julialang.org/en/v1/manual/metaprogramming/}{Julia} and \href{https://docs.racket-lang.org/reference/quasiquote.html}{Racket}. In base R, quasiquotation is performed with \code{\link[=bquote]{bquote()}}.
The main difference between rlang and other languages is that quasiquotation is often implicit instead of explicit. You can use injection operators in any defusing / quoting function (unless that function defuses its argument with a special operator like \code{\link[=enquo0]{enquo0()}}). This is not the case in lisp languages for example where injection / unquoting is explicit and only enabled within a backquote.
}
\section{See also}{
\itemize{
\item \ifelse{html}{\link[=topic-inject-out-of-context]{What happens if I use injection operators out of context?}}{\link[=topic-inject-out-of-context]{What happens if I use injection operators out of context?}}
}
}
\keyword{internal}
rlang/man/enquo.Rd 0000644 0001762 0000144 00000010162 14175213516 013553 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nse-defuse.R
\name{enquo}
\alias{enquo}
\alias{enquos}
\title{Defuse function arguments}
\usage{
enquo(arg)
enquos(
...,
.named = FALSE,
.ignore_empty = c("trailing", "none", "all"),
.unquote_names = TRUE,
.homonyms = c("keep", "first", "last", "error"),
.check_assign = FALSE
)
}
\arguments{
\item{arg}{An unquoted argument name. The expression
supplied to that argument is defused and returned.}
\item{...}{Names of arguments to defuse.}
\item{.named}{If \code{TRUE}, unnamed inputs are automatically named
with \code{\link[=as_label]{as_label()}}. This is equivalent to applying
\code{\link[=exprs_auto_name]{exprs_auto_name()}} on the result. If \code{FALSE}, unnamed elements
are left as is and, if fully unnamed, the list is given minimal
names (a vector of \code{""}). If \code{NULL}, fully unnamed results are
left with \code{NULL} names.}
\item{.ignore_empty}{Whether to ignore empty arguments. Can be one
of \code{"trailing"}, \code{"none"}, \code{"all"}. If \code{"trailing"}, only the
last argument is ignored if it is empty. Named arguments are not
considered empty.}
\item{.unquote_names}{Whether to treat \verb{:=} as \code{=}. Unlike \code{=}, the
\verb{:=} syntax supports \link[=glue-operators]{names injection}.}
\item{.homonyms}{How to treat arguments with the same name. The
default, \code{"keep"}, preserves these arguments. Set \code{.homonyms} to
\code{"first"} to only keep the first occurrences, to \code{"last"} to keep
the last occurrences, and to \code{"error"} to raise an informative
error and indicate what arguments have duplicated names.}
\item{.check_assign}{Whether to check for \verb{<-} calls. When \code{TRUE} a
warning recommends users to use \code{=} if they meant to match a
function parameter or wrap the \verb{<-} call in curly braces otherwise.
This ensures assignments are explicit.}
}
\value{
\code{enquo()} returns a \link[=topic-quosure]{quosure} and \code{enquos()}
returns a list of quosures.
}
\description{
\code{enquo()} and \code{enquos()} \link[=topic-defuse]{defuse} function arguments.
A defused expression can be examined, modified, and injected into
other expressions.
Defusing function arguments is useful for:
\itemize{
\item Creating data-masking functions.
\item Interfacing with another \link[=topic-data-mask]{data-masking} function
using the \link[=topic-metaprogramming]{defuse-and-inject} pattern.
}
These are advanced tools. Make sure to first learn about the embrace
operator \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}} in \ifelse{html}{\link[=topic-data-mask-programming]{Data mask programming patterns}}{\link[=topic-data-mask-programming]{Data mask programming patterns}}.
\verb{\{\{} is easier to work with with less theory, and it is sufficient
in most applications.
}
\section{Implicit injection}{
Arguments defused with \code{enquo()} and \code{enquos()} automatically gain
\link[=topic-inject]{injection} support.\if{html}{\out{
}}\preformatted{my_mean <- function(data, var) \{
var <- enquo(var)
dplyr::summarise(data, mean(!!var))
\}
# Can now use `!!` and `\{\{`
my_mean(mtcars, !!sym("cyl"))
}\if{html}{\out{
}}
See \code{\link[=enquo0]{enquo0()}} and \code{\link[=enquos0]{enquos0()}} for variants that don't enable
injection.
}
\examples{
# `enquo()` defuses the expression supplied by your user
f <- function(arg) {
enquo(arg)
}
f(1 + 1)
# `enquos()` works with arguments and dots. It returns a list of
# expressions
f <- function(...) {
enquos(...)
}
f(1 + 1, 2 * 10)
# `enquo()` and `enquos()` enable _injection_ and _embracing_ for
# your users
g <- function(arg) {
f({{ arg }} * 2)
}
g(100)
column <- sym("cyl")
g(!!column)
}
\seealso{
\itemize{
\item \ifelse{html}{\link[=topic-defuse]{Defusing R expressions}}{\link[=topic-defuse]{Defusing R expressions}} for an overview.
\item \code{\link[=expr]{expr()}} to defuse your own local expressions.
\item \link[=defusing-advanced]{Advanced defusal operators}.
\item \code{\link[base:eval]{base::eval()}} and \code{\link[=eval_bare]{eval_bare()}} for resuming evaluation
of a defused expression.
}
}
rlang/man/is_integerish.Rd 0000644 0001762 0000144 00000003245 14127057575 015274 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/types.R
\name{is_integerish}
\alias{is_integerish}
\alias{is_bare_integerish}
\alias{is_scalar_integerish}
\title{Is a vector integer-like?}
\usage{
is_integerish(x, n = NULL, finite = NULL)
is_bare_integerish(x, n = NULL, finite = NULL)
is_scalar_integerish(x, finite = NULL)
}
\arguments{
\item{x}{Object to be tested.}
\item{n}{Expected length of a vector.}
\item{finite}{Whether all values of the vector are finite. The
non-finite values are \code{NA}, \code{Inf}, \code{-Inf} and \code{NaN}. Setting this
to something other than \code{NULL} can be expensive because the whole
vector needs to be traversed and checked.}
}
\description{
These predicates check whether R considers a number vector to be
integer-like, according to its own tolerance check (which is in
fact delegated to the C library). This function is not adapted to
data analysis, see the help for \code{\link[base:integer]{base::is.integer()}} for examples
of how to check for whole numbers.
Things to consider when checking for integer-like doubles:
\itemize{
\item This check can be expensive because the whole double vector has
to be traversed and checked.
\item Large double values may be integerish but may still not be
coercible to integer. This is because integers in R only support
values up to \code{2^31 - 1} while numbers stored as double can be
much larger.
}
}
\examples{
is_integerish(10L)
is_integerish(10.0)
is_integerish(10.0, n = 2)
is_integerish(10.000001)
is_integerish(TRUE)
}
\seealso{
\code{\link[=is_bare_numeric]{is_bare_numeric()}} for testing whether an object is a
base numeric type (a bare double or integer vector).
}
rlang/man/global_prompt_install.Rd 0000644 0001762 0000144 00000001421 14175213516 017011 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-handlers.R
\name{global_prompt_install}
\alias{global_prompt_install}
\title{Prompt user to install missing packages}
\usage{
global_prompt_install(enable = TRUE)
}
\arguments{
\item{enable}{Whether to enable or disable global handling.}
}
\description{
When enabled, \code{packageNotFoundError} thrown by \code{\link[=loadNamespace]{loadNamespace()}}
cause a user prompt to install the missing package and continue
without interrupting the current program.
This is similar to how \code{\link[=check_installed]{check_installed()}} prompts users to install
required packages. It uses the same install strategy, using pak if
available and \code{\link[=install.packages]{install.packages()}} otherwise.
}
rlang/man/cnd_signal.Rd 0000644 0001762 0000144 00000004000 14175213516 014517 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-signal.R
\name{cnd_signal}
\alias{cnd_signal}
\title{Signal a condition object}
\usage{
cnd_signal(cnd, ...)
}
\arguments{
\item{cnd}{A condition object (see \code{\link[=cnd]{cnd()}}). If \code{NULL},
\code{cnd_signal()} returns without signalling a condition.}
\item{...}{These dots are for future extensions and must be empty.}
}
\description{
\code{cnd_signal()} takes a condition as argument and emits the
corresponding signal. The type of signal depends on the class of
the condition:
\itemize{
\item A message is signalled if the condition inherits from
\code{"message"}. This is equivalent to signalling with \code{\link[=inform]{inform()}} or
\code{\link[base:message]{base::message()}}.
\item A warning is signalled if the condition inherits from
\code{"warning"}. This is equivalent to signalling with \code{\link[=warn]{warn()}} or
\code{\link[base:warning]{base::warning()}}.
\item An error is signalled if the condition inherits from
\code{"error"}. This is equivalent to signalling with \code{\link[=abort]{abort()}} or
\code{\link[base:stop]{base::stop()}}.
\item An interrupt is signalled if the condition inherits from
\code{"interrupt"}. This is equivalent to signalling with
\code{\link[=interrupt]{interrupt()}}.
}
}
\examples{
# The type of signal depends on the class. If the condition
# inherits from "warning", a warning is issued:
cnd <- warning_cnd("my_warning_class", message = "This is a warning")
cnd_signal(cnd)
# If it inherits from "error", an error is raised:
cnd <- error_cnd("my_error_class", message = "This is an error")
try(cnd_signal(cnd))
}
\seealso{
\itemize{
\item \code{\link[=cnd_type]{cnd_type()}} to determine the type of a condition.
\item \code{\link[=abort]{abort()}}, \code{\link[=warn]{warn()}} and \code{\link[=inform]{inform()}} for creating and signalling
structured R conditions in one go.
\item \code{\link[=try_fetch]{try_fetch()}} for establishing condition handlers for
particular condition classes.
}
}
rlang/man/env_binding_are_active.Rd 0000644 0001762 0000144 00000001304 14175213516 017066 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-binding.R
\name{env_binding_are_active}
\alias{env_binding_are_active}
\alias{env_binding_are_lazy}
\title{What kind of environment binding?}
\usage{
env_binding_are_active(env, nms = NULL)
env_binding_are_lazy(env, nms = NULL)
}
\arguments{
\item{env}{An environment.}
\item{nms}{Names of bindings. Defaults to all bindings in \code{env}.}
}
\value{
A logical vector as long as \code{nms} and named after it.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
}
\keyword{internal}
rlang/man/env_depth.Rd 0000644 0001762 0000144 00000001227 14127057575 014412 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env.R
\name{env_depth}
\alias{env_depth}
\title{Depth of an environment chain}
\usage{
env_depth(env)
}
\arguments{
\item{env}{An environment.}
}
\value{
An integer.
}
\description{
This function returns the number of environments between \code{env} and
the \link[=empty_env]{empty environment}, including \code{env}. The depth of
\code{env} is also the number of parents of \code{env} (since the empty
environment counts as a parent).
}
\examples{
env_depth(empty_env())
env_depth(pkg_env("rlang"))
}
\seealso{
The section on inheritance in \code{\link[=env]{env()}} documentation.
}
rlang/man/check_dots_used.Rd 0000644 0001762 0000144 00000003554 14175213516 015561 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dots-ellipsis.R
\name{check_dots_used}
\alias{check_dots_used}
\title{Check that all dots have been used}
\usage{
check_dots_used(
env = caller_env(),
call = caller_env(),
error = NULL,
action = deprecated()
)
}
\arguments{
\item{env}{Environment in which to look for \code{...} and to set up handler.}
\item{call}{The execution environment of a currently
running function, e.g. \code{caller_env()}. The function will be
mentioned in error messages as the source of the error. See the
\code{call} argument of \code{\link[=abort]{abort()}} for more information.}
\item{error}{An optional error handler passed to \code{\link[=try_fetch]{try_fetch()}}. Use
this e.g. to demote an error into a warning.}
\item{action}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}}
}
\description{
When \code{...} arguments are passed to methods, it is assumed there
method will match and use these arguments. If this isn't the case,
this often indicates a programming error. Call \code{check_dots_used()}
to fail with an error when unused arguments are detected.
}
\details{
In packages, document \code{...} with this standard tag:\preformatted{ @inheritParams rlang::args_dots_used
}
\code{check_dots_used()} implicitly calls \code{\link[=on.exit]{on.exit()}} to check that all
elements of \code{...} have been used when the function exits. If you
use \code{\link[=on.exit]{on.exit()}} elsewhere in your function, make sure to use \code{add = TRUE} so that you don't override the handler set up by
\code{check_dots_used()}.
}
\examples{
f <- function(...) {
check_dots_used()
g(...)
}
g <- function(x, y, ...) {
x + y
}
f(x = 1, y = 2)
try(f(x = 1, y = 2, z = 3))
try(f(x = 1, y = 2, 3, 4, 5))
}
rlang/man/scalar-type-predicates.Rd 0000644 0001762 0000144 00000002464 14175213516 016777 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/types.R
\name{scalar-type-predicates}
\alias{scalar-type-predicates}
\alias{is_scalar_list}
\alias{is_scalar_atomic}
\alias{is_scalar_vector}
\alias{is_scalar_integer}
\alias{is_scalar_double}
\alias{is_scalar_complex}
\alias{is_scalar_character}
\alias{is_scalar_logical}
\alias{is_scalar_raw}
\alias{is_string}
\alias{is_scalar_bytes}
\alias{is_bool}
\title{Scalar type predicates}
\usage{
is_scalar_list(x)
is_scalar_atomic(x)
is_scalar_vector(x)
is_scalar_integer(x)
is_scalar_double(x)
is_scalar_complex(x)
is_scalar_character(x)
is_scalar_logical(x)
is_scalar_raw(x)
is_string(x, string = NULL)
is_scalar_bytes(x)
is_bool(x)
}
\arguments{
\item{x}{object to be tested.}
\item{string}{A string to compare to \code{x}. If a character vector,
returns \code{TRUE} if at least one element is equal to \code{x}.}
}
\description{
These predicates check for a given type and whether the vector is
"scalar", that is, of length 1.
In addition to the length check, \code{is_string()} and \code{is_bool()}
return \code{FALSE} if their input is missing. This is useful for
type-checking arguments, when your function expects a single string
or a single \code{TRUE} or \code{FALSE}.
}
\seealso{
\link{type-predicates}, \link{bare-type-predicates}
}
rlang/man/fn_body.Rd 0000644 0001762 0000144 00000001560 14175213516 014046 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fn.R
\name{fn_body}
\alias{fn_body}
\alias{fn_body<-}
\title{Get or set function body}
\usage{
fn_body(fn = caller_fn())
fn_body(fn) <- value
}
\arguments{
\item{fn}{A function. It is looked up in the calling frame if not
supplied.}
\item{value}{New formals or formals names for \code{fn}.}
}
\description{
\code{fn_body()} is a simple wrapper around \code{\link[base:body]{base::body()}}. It always
returns a \verb{\\\{} expression and throws an error when the input is a
primitive function (whereas \code{body()} returns \code{NULL}). The setter
version preserves attributes, unlike \verb{body<-}.
}
\examples{
# fn_body() is like body() but always returns a block:
fn <- function() do()
body(fn)
fn_body(fn)
# It also throws an error when used on a primitive function:
try(fn_body(base::list))
}
rlang/man/is_interactive.Rd 0000644 0001762 0000144 00000002625 14127057575 015451 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/state.R
\name{is_interactive}
\alias{is_interactive}
\alias{local_interactive}
\alias{with_interactive}
\title{Is R running interactively?}
\usage{
is_interactive()
local_interactive(value = TRUE, frame = caller_env())
with_interactive(expr, value = TRUE)
}
\arguments{
\item{value}{A single \code{TRUE} or \code{FALSE}. This overrides the return
value of \code{is_interactive()}.}
\item{frame}{The environment of a running function which defines
the scope of the temporary options. When the function returns,
the options are reset to their original values.}
\item{expr}{An expression to evaluate with interactivity set to
\code{value}.}
}
\description{
Like \code{\link[base:interactive]{base::interactive()}}, \code{is_interactive()} returns \code{TRUE} when
the function runs interactively and \code{FALSE} when it runs in batch
mode. It also checks, in this order:
\itemize{
\item The \code{rlang_interactive} global option. If set to a single \code{TRUE}
or \code{FALSE}, \code{is_interactive()} returns that value immediately. This
escape hatch is useful in unit tests or to manually turn on
interactive features in RMarkdown outputs.
\item Whether knitr or testthat is in progress, in which case
\code{is_interactive()} returns \code{FALSE}.
}
\code{with_interactive()} and \code{local_interactive()} set the global
option conveniently.
}
rlang/man/done.Rd 0000644 0001762 0000144 00000001425 14127057575 013363 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/s3.R
\name{done}
\alias{done}
\alias{is_done_box}
\title{Box a final value for early termination}
\usage{
done(x)
is_done_box(x, empty = NULL)
}
\arguments{
\item{x}{For \code{done()}, a value to box. For \code{is_done_box()}, a
value to test.}
\item{empty}{Whether the box is empty. If \code{NULL}, \code{is_done_box()}
returns \code{TRUE} for all done boxes. If \code{TRUE}, it returns \code{TRUE}
only for empty boxes. Otherwise it returns \code{TRUE} only for
non-empty boxes.}
}
\value{
A \link[=new_box]{boxed} value.
}
\description{
A value boxed with \code{done()} signals to its caller that it
should stop iterating. Use it to shortcircuit a loop.
}
\examples{
done(3)
x <- done(3)
is_done_box(x)
}
rlang/man/topic-metaprogramming.Rd 0000644 0001762 0000144 00000032744 14175213516 016743 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/topic-nse.R
\name{topic-metaprogramming}
\alias{topic-metaprogramming}
\title{Metaprogramming patterns}
\description{
The patterns covered in this article rely on \emph{metaprogramming}, the ability to defuse, create, expand, and inject R expressions. A good place to start if you're new to programming on the language is the \href{https://adv-r.hadley.nz/metaprogramming.html}{Metaprogramming chapter} of the \href{https://adv-r.hadley.nz}{Advanced R} book.
If you haven't already, read \ifelse{html}{\link[=topic-data-mask-programming]{Data mask programming patterns}}{\link[=topic-data-mask-programming]{Data mask programming patterns}} which covers simpler patterns that do not require as much theory to get up to speed. It covers concepts like argument behaviours and the various patterns you can add to your toolbox (forwarding, names, bridge, and transformative patterns).
}
\section{Forwarding patterns}{
\subsection{Defuse and inject}{
\ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}} and \code{...} are sufficient for most purposes. Sometimes however, it is necessary to decompose the forwarding action into its two constitutive steps, \link[=topic-defuse]{defusing} and \link[=topic-inject]{injecting}.
\verb{\{\{} is the combination of \code{\link[=enquo]{enquo()}} and \code{\link[=injection-operator]{!!}}. These functions are completely equivalent:\if{html}{\out{
}}\preformatted{my_summarise <- function(data, var) \{
data \%>\% dplyr::summarise(\{\{ var \}\})
\}
my_summarise <- function(data, var) \{
data \%>\% dplyr::summarise(!!enquo(var))
\}
}\if{html}{\out{
}}
Passing \code{...} is equivalent to the combination of \code{\link[=enquos]{enquos()}} and \code{\link[=splice-operator]{!!!}}:\if{html}{\out{
}}
The advantage of decomposing the steps is that you gain access to the \link[=topic-defuse]{defused expressions}. Once defused, you can inspect or modify the expressions before injecting them in their target context.
}
\subsection{Inspecting input labels}{
For instance, here is how to create an automatic name for a defused argument using \code{\link[=as_label]{as_label()}}:\if{html}{\out{
}}
With multiple arguments, use the plural variant \code{\link[=enquos]{enquos()}}. Set \code{.named} to \code{TRUE} to automatically call \code{\link[=as_label]{as_label()}} on the inputs for which the user has not provided a name (the same behaviour as in most dplyr verbs):\if{html}{\out{
}}
Defuse-and-inject patterns are most useful for transforming inputs. Some applications are explored in the Transformation patterns section.
}
}
\section{Names patterns}{
\subsection{Symbolise and inject}{
The symbolise-and-inject pattern is a \emph{names pattern} that you can use when \code{across(all_of())} is not supported. It consists in creating \link[=topic-defuse]{defused expressions} that refer to the data-variables represented in the names vector. These are then injected in the data mask context.
Symbolise a single string with \code{\link[=sym]{sym()}} or \code{\link[=data_sym]{data_sym()}}:\if{html}{\out{
}}
Simple symbols returned by \code{sym()} and \code{syms()} work in a wider variety of cases (with base functions in particular) but we'll use mostly use \code{data_sym()} and \code{data_syms()} because they are more robust (see \ifelse{html}{\link[=topic-data-mask-ambiguity]{The data mask ambiguity}}{\link[=topic-data-mask-ambiguity]{The data mask ambiguity}}). Note that these do not return \emph{symbols} per se, instead they create \emph{calls} to \code{$} that subset the \code{\link{.data}} pronoun.
Since the \code{.data} pronoun is a tidy eval feature, you can't use it in base functions. As a rule, prefer the \code{data_}-prefixed variants when you're injecting in tidy eval functions and the unprefixed functions for base functions.
A list of symbols can be injected in data-masked dots with the splice operator \code{\link[=splice-operator]{!!!}}, which injects each element of the list as a separate argument. For instance, to implement a \code{group_by()} variant that takes a character vector of column names, you might write:\if{html}{\out{
}}
In more complex case, you might want to add R code around the symbols. This requires \emph{transformation} patterns, see the section below.
}
}
\section{Bridge patterns}{
\subsection{\code{mutate()} as a data-mask to selection bridge}{
This is a variant of the \code{transmute()} bridge pattern described in \ifelse{html}{\link[=topic-data-mask-programming]{Data mask programming patterns}}{\link[=topic-data-mask-programming]{Data mask programming patterns}} that does not materialise \code{...} in the intermediate step. Instead, the \code{...} expressions are defused and inspected. Then the expressions, rather than the columns, are spliced in \code{mutate()}.\if{html}{\out{
}}\preformatted{my_pivot_longer <- function(data, ...) \{
# Defuse the dots and inspect the names
dots <- enquos(..., .named = TRUE)
names <- names(dots)
# Pass the inputs to `mutate()`
data <- data \%>\% dplyr::mutate(!!!dots)
# Select `...` inputs by name with `all_of()`
data \%>\%
tidyr::pivot_longer(cols = all_of(names))
\}
mtcars \%>\% my_pivot_longer(cyl, am = am * 100)
}\if{html}{\out{
}}
\enumerate{
\item Defuse the \code{...} expressions. The \code{.named} argument ensures unnamed inputs get a default name, just like they would if passed to \code{mutate()}. Take the names of the list of inputs.
\item Once we have the names, inject the argument expressions into \code{mutate()} to update the data frame.
\item Finally, pass the names to the tidy selection via \href{https://tidyselect.r-lib.org/reference/all_of.html}{\code{all_of()}}.
}
}
}
\section{Transformation patterns}{
\subsection{Transforming inputs manually}{
If \code{across()} and variants are not available, you will need to transform the inputs yourself using metaprogramming techniques. To illustrate the technique we'll reimplement \code{my_mean()} and without using \code{across()}. The pattern consists in defusing the input expression, building larger calls around them, and finally inject the modified expressions inside the data-masking functions.
We'll start with a single named argument for simplicity:\if{html}{\out{
}}\preformatted{my_mean <- function(data, var) \{
# Defuse the expression
var <- enquo(var)
# Wrap it in a call to `mean()`
var <- expr(mean(!!var, na.rm = TRUE))
# Inject the expanded expression
data \%>\% dplyr::summarise(mean = !!var)
\}
mtcars \%>\% my_mean(cyl)
#> # A tibble: 1 x 1
#> mean
#>
#> 1 6.19
}\if{html}{\out{
}}
With \code{...} the technique is similar, though a little more involved. We'll use the plural variants \code{enquos()} and \code{\link{!!!}}. We'll also loop over the variable number of inputs using \code{purrr::map()}. But the pattern is otherwise basically the same:\if{html}{\out{
}}\preformatted{my_mean <- function(.data, ...) \{
# Defuse the dots. Make sure they are automatically named.
vars <- enquos(..., .named = TRUE)
# Map over each defused expression and wrap it in a call to `mean()`
vars <- purrr::map(vars, ~ expr(mean(!!.x, na.rm = TRUE)))
# Inject the expressions
.data \%>\% dplyr::summarise(!!!vars)
\}
mtcars \%>\% my_mean(cyl)
#> # A tibble: 1 x 1
#> cyl
#>
#> 1 6.19
}\if{html}{\out{
}}
Note that we are inheriting the data-masking behaviour of \code{summarise()} because we have effectively forwarded \code{...} inside that verb. This is different than transformation patterns based on \code{across()} which inherit tidy selection behaviour. In practice, this means the function doesn't support selection helpers and syntax. Instead, it gains the ability to create new vectors on the fly:\if{html}{\out{
}}
}
}
\section{Base patterns}{
In this section, we review patterns for programming with \emph{base} data-masking functions. They essentially consist in building and evaluating expressions in the data mask. We review these patterns and compare them to rlang idioms.
\subsection{Data-masked \code{get()}}{
In the simplest version of this pattern, \code{get()} is called with a variable name to retrieve objects from the data mask:\if{html}{\out{
}}
This sort of pattern is susceptible to \link[=topic-data-mask-ambiguity]{names collisions}. For instance, the input data frame might contain a variable called \code{var}:\if{html}{\out{
}}\preformatted{df <- data.frame(var = "wrong")
with(df, mean(get(var)))
#> Error in get(var): object 'wrong' not found
}\if{html}{\out{
}}
In general, prefer symbol injection over \code{get()} to prevent this sort of collisions. With base functions you will need to enable injection operators explicitly using \code{\link[=inject]{inject()}}:\if{html}{\out{
}}
See \ifelse{html}{\link[=topic-data-mask-ambiguity]{The data mask ambiguity}}{\link[=topic-data-mask-ambiguity]{The data mask ambiguity}} for more information about names collisions.
}
\subsection{Data-masked \code{parse()} and \code{eval()}}{
A more involved pattern consists in building R code in a string and evaluating it in the mask:\if{html}{\out{
}}
As before, the \code{code} variable is vulnerable to \link[=topic-data-mask-ambiguity]{names collisions}. More importantly, if \code{var1} and \code{var2} are user inputs, they could contain \href{https://xkcd.com/327/}{adversarial code}. Evaluating code assembled from strings is always a risky business:\if{html}{\out{
}}\preformatted{var1 <- "(function() \{
Sys.sleep(Inf) # Could be a coin mining routine
\})()"
var2 <- "vs"
code <- paste(var1, "==", var2)
with(mtcars, mean(eval(parse(text = code))))
}\if{html}{\out{
}}
This is not a big deal if your code is only used internally. However, this code could be part of a public Shiny app which Internet users could exploit. But even internally, parsing is a source of bugs when variable names contain syntactic symbols like \code{-} or \code{:}.\if{html}{\out{
}}
For these reasons, always prefer to \emph{build} code instead of parsing code. Building variable names with \code{\link[=sym]{sym()}} is a way of sanitising inputs.\if{html}{\out{
}}\preformatted{var1 <- "(function() \{
Sys.sleep(Inf) # Could be a coin mining routine
\})()"
var2 <- "vs"
code <- call("==", sym(var1), sym(var2))
code
#> `(function() \{\\n Sys.sleep(Inf) # Could be a coin mining routine\\n\})()` ==
#> vs
}\if{html}{\out{
}}
The adversarial input now produces an error:\if{html}{\out{
}}\preformatted{with(mtcars, mean(eval(code)))
#> Error in eval(code): object '(function() \{\\n Sys.sleep(Inf) # Could be a coin mining routine\\n\})()' not found
}\if{html}{\out{
}}
Finally, it is recommended to inject the code instead of evaluating it to avoid names collisions:\if{html}{\out{
}}
}
}
\keyword{internal}
rlang/man/box.Rd 0000644 0001762 0000144 00000002777 14127057575 013241 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/s3.R
\name{box}
\alias{box}
\alias{new_box}
\alias{is_box}
\alias{unbox}
\title{Box a value}
\usage{
new_box(.x, class = NULL, ...)
is_box(x, class = NULL)
unbox(box)
}
\arguments{
\item{class}{For \code{new_box()}, an additional class for the
boxed value (in addition to \code{rlang_box}). For \code{is_box()}, a class
or vector of classes passed to \code{\link[=inherits_all]{inherits_all()}}.}
\item{...}{Additional attributes passed to \code{\link[base:structure]{base::structure()}}.}
\item{x, .x}{An R object.}
\item{box}{A boxed value to unbox.}
}
\description{
\code{new_box()} is similar to \code{\link[base:AsIs]{base::I()}} but it protects a value by
wrapping it in a scalar list rather than by adding an attribute.
\code{unbox()} retrieves the boxed value. \code{is_box()} tests whether an
object is boxed with optional class. \code{as_box()} ensures that a
value is wrapped in a box. \code{as_box_if()} does the same but only if
the value matches a predicate.
}
\examples{
boxed <- new_box(letters, "mybox")
is_box(boxed)
is_box(boxed, "mybox")
is_box(boxed, "otherbox")
unbox(boxed)
# as_box() avoids double-boxing:
boxed2 <- as_box(boxed, "mybox")
boxed2
unbox(boxed2)
# Compare to:
boxed_boxed <- new_box(boxed, "mybox")
boxed_boxed
unbox(unbox(boxed_boxed))
# Use `as_box_if()` with a predicate if you need to ensure a box
# only for a subset of values:
as_box_if(NULL, is_null, "null_box")
as_box_if("foo", is_null, "null_box")
}
rlang/man/topic-condition-customisation.Rd 0000644 0001762 0000144 00000007732 14175213516 020436 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/topic-errors.R
\name{topic-condition-customisation}
\alias{topic-condition-customisation}
\title{Customising condition messages}
\description{
Various aspects of the condition messages displayed by \code{\link[=abort]{abort()}}, \code{\link[=warn]{warn()}}, and \code{\link[=inform]{inform()}} can be customised using options from the \href{https://cli.r-lib.org}{cli} package.
}
\section{Turning off unicode bullets}{
By default, bulleted lists are prefixed with unicode symbols:
\ifelse{latex}{\emph{Not in PDF manual.}}{\if{html}{\out{
}}}
Set this option to use simple letters instead:\if{html}{\out{
}}\preformatted{options(cli.condition_unicode_bullets = FALSE)
rlang::abort(c(
"The error message.",
"*" = "Regular bullet.",
"i" = "Informative bullet.",
"x" = "Cross bullet.",
"v" = "Victory bullet.",
">" = "Arrow bullet."
))
#> Error:
#> ! The error message.
#> * Regular bullet.
#> i Informative bullet.
#> x Cross bullet.
#> v Victory bullet.
#> > Arrow bullet.
}\if{html}{\out{
}}
}
\section{Changing the bullet symbols}{
You can specify what symbol to use for each type of bullet through your cli user theme. For instance, here is how to uniformly use \code{*} for all bullet kinds:\if{html}{\out{
}}
}
\section{Changing the foreground and background colour of error calls}{
When called inside a function, \code{abort()} displays the function call to help contextualise the error:\if{html}{\out{
}}\preformatted{splash <- function() \{
abort("Can't splash without water.")
\}
splash()
#> Error in `splash()`:
#> ! Can't splash without water.
}\if{html}{\out{
}}
The call is formatted with cli as a \code{code} element. This is not visible in the manual, but code text is formatted with a highlighted background colour by default. When this can be reliably detected, that background colour is different depending on whether you're using a light or dark theme.
You can override the colour of code elements in your cli theme. Here is my personal configuration that fits well with the colour theme I currently use in my IDE:\if{html}{\out{
}}
}
\keyword{internal}
rlang/man/quo_expr.Rd 0000644 0001762 0000144 00000001556 14175213516 014275 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{quo_expr}
\alias{quo_expr}
\title{Squash a quosure}
\usage{
quo_expr(quo, warn = FALSE)
}
\arguments{
\item{quo}{A quosure or expression.}
\item{warn}{Whether to warn if the quosure contains other quosures
(those will be collapsed). This is useful when you use
\code{quo_squash()} in order to make a non-tidyeval API compatible
with quosures. In that case, getting rid of the nested quosures
is likely to cause subtle bugs and it is good practice to warn
the user about it.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
This function is deprecated, please use \code{\link[=quo_squash]{quo_squash()}} instead.
}
\keyword{internal}
rlang/man/is_named.Rd 0000644 0001762 0000144 00000003631 14175213516 014206 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/attr.R
\name{is_named}
\alias{is_named}
\alias{is_named2}
\alias{have_name}
\title{Is object named?}
\usage{
is_named(x)
is_named2(x)
have_name(x)
}
\arguments{
\item{x}{A vector to test.}
}
\value{
\code{is_named()} and \code{is_named2()} are scalar predicates that
return \code{TRUE} or \code{FALSE}. \code{have_name()} is vectorised and returns
a logical vector as long as the input.
}
\description{
\itemize{
\item \code{is_named()} is a scalar predicate that checks that \code{x} has a
\code{names} attribute and that none of the names are missing or empty
(\code{NA} or \code{""}).
\item \code{is_named2()} is like \code{is_named()} but always returns \code{TRUE} for
empty vectors, even those that don't have a \code{names} attribute.
In other words, it tests for the property that each element of a
vector is named. \code{is_named2()} composes well with \code{\link[=names2]{names2()}}
whereas \code{is_named()} composes with \code{names()}.
\item \code{have_name()} is a vectorised variant.
}
}
\details{
\code{is_named()} always returns \code{TRUE} for empty vectors because
}
\examples{
# is_named() is a scalar predicate about the whole vector of names:
is_named(c(a = 1, b = 2))
is_named(c(a = 1, 2))
# Unlike is_named2(), is_named() returns `FALSE` for empty vectors
# that don't have a `names` attribute.
is_named(list())
is_named2(list())
# have_name() is a vectorised predicate
have_name(c(a = 1, b = 2))
have_name(c(a = 1, 2))
# Empty and missing names are treated as invalid:
invalid <- set_names(letters[1:5])
names(invalid)[1] <- ""
names(invalid)[3] <- NA
is_named(invalid)
have_name(invalid)
# A data frame normally has valid, unique names
is_named(mtcars)
have_name(mtcars)
# A matrix usually doesn't because the names are stored in a
# different attribute
mat <- matrix(1:4, 2)
colnames(mat) <- c("a", "b")
is_named(mat)
names(mat)
}
rlang/man/is_copyable.Rd 0000644 0001762 0000144 00000001760 14127057575 014731 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/types.R
\name{is_copyable}
\alias{is_copyable}
\title{Is an object copyable?}
\usage{
is_copyable(x)
}
\arguments{
\item{x}{An object to test.}
}
\description{
When an object is modified, R generally copies it (sometimes
lazily) to enforce \href{https://en.wikipedia.org/wiki/Value_semantics}{value semantics}.
However, some internal types are uncopyable. If you try to copy
them, either with \verb{<-} or by argument passing, you actually create
references to the original object rather than actual
copies. Modifying these references can thus have far reaching side
effects.
}
\examples{
# Let's add attributes with structure() to uncopyable types. Since
# they are not copied, the attributes are changed in place:
env <- env()
structure(env, foo = "bar")
env
# These objects that can only be changed with side effect are not
# copyable:
is_copyable(env)
structure(base::list, foo = "bar")
str(base::list)
}
\keyword{internal}
rlang/man/args_dots_used.Rd 0000644 0001762 0000144 00000000625 14175213516 015434 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dots-ellipsis.R
\name{args_dots_used}
\alias{args_dots_used}
\title{Helper for consistent documentation of used dots}
\arguments{
\item{...}{Arguments passed to methods.}
}
\description{
Use \verb{@inheritParams rlang::args_dots_used} in your package
to consistently document \code{...} that must be used.
}
\keyword{internal}
rlang/man/duplicate.Rd 0000644 0001762 0000144 00000001403 14175213516 014374 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/obj.R
\name{duplicate}
\alias{duplicate}
\title{Duplicate an R object}
\usage{
duplicate(x, shallow = FALSE)
}
\arguments{
\item{x}{An R object. Uncopyable objects like symbols and
environments are returned as is (just like with \verb{<-}).}
\item{shallow}{Recursive data structures like lists, calls and
pairlists are duplicated in full by default. A shallow copy only
duplicates the top-level data structure.}
}
\description{
\code{duplicate()} is an interface to the C-level \code{duplicate()} and
\code{shallow_duplicate()} functions. It is mostly meant for users of
the C API of R, e.g. for debugging, experimenting, or prototyping C
code in R.
}
\seealso{
pairlist
}
\keyword{internal}
rlang/man/set_expr.Rd 0000644 0001762 0000144 00000002734 14175213516 014263 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expr.R
\name{set_expr}
\alias{set_expr}
\alias{get_expr}
\title{Set and get an expression}
\usage{
set_expr(x, value)
get_expr(x, default = x)
}
\arguments{
\item{x}{An expression, closure, or one-sided formula. In addition,
\code{set_expr()} accept frames.}
\item{value}{An updated expression.}
\item{default}{A default expression to return when \code{x} is not an
expression wrapper. Defaults to \code{x} itself.}
}
\value{
The updated original input for \code{set_expr()}. A raw
expression for \code{get_expr()}.
}
\description{
These helpers are useful to make your function work generically
with quosures and raw expressions. First call \code{get_expr()} to
extract an expression. Once you're done processing the expression,
call \code{set_expr()} on the original object to update the expression.
You can return the result of \code{set_expr()}, either a formula or an
expression depending on the input type. Note that \code{set_expr()} does
not change its input, it creates a new object.
}
\examples{
f <- ~foo(bar)
e <- quote(foo(bar))
frame <- identity(identity(ctxt_frame()))
get_expr(f)
get_expr(e)
get_expr(frame)
set_expr(f, quote(baz))
set_expr(e, quote(baz))
}
\seealso{
\code{\link[=quo_get_expr]{quo_get_expr()}} and \code{\link[=quo_set_expr]{quo_set_expr()}} for versions of
\code{\link[=get_expr]{get_expr()}} and \code{\link[=set_expr]{set_expr()}} that only work on quosures.
}
\keyword{internal}
rlang/man/raw_deparse_str.Rd 0000644 0001762 0000144 00000001607 14175213516 015614 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/raw.R
\name{raw_deparse_str}
\alias{raw_deparse_str}
\title{Serialize a raw vector to a string}
\usage{
raw_deparse_str(x, prefix = NULL, suffix = NULL)
}
\arguments{
\item{x}{A raw vector.}
\item{prefix, suffix}{Prefix and suffix strings, or `NULL.}
}
\value{
A string.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
This function converts a raw vector to a hexadecimal string,
optionally adding a prefix and a suffix.
It is roughly equivalent to
\code{paste0(prefix, paste(format(x), collapse = ""), suffix)}
and much faster.
}
\examples{
raw_deparse_str(raw())
raw_deparse_str(charToRaw("string"))
raw_deparse_str(raw(10), prefix = "'0x", suffix = "'")
}
\keyword{internal}
rlang/man/quo_squash.Rd 0000644 0001762 0000144 00000002556 14175213516 014624 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/quo.R
\name{quo_squash}
\alias{quo_squash}
\title{Squash a quosure}
\usage{
quo_squash(quo, warn = FALSE)
}
\arguments{
\item{quo}{A quosure or expression.}
\item{warn}{Whether to warn if the quosure contains other quosures
(those will be collapsed). This is useful when you use
\code{quo_squash()} in order to make a non-tidyeval API compatible
with quosures. In that case, getting rid of the nested quosures
is likely to cause subtle bugs and it is good practice to warn
the user about it.}
}
\description{
\code{quo_squash()} flattens all nested quosures within an expression.
For example it transforms \verb{^foo(^bar(), ^baz)} to the bare
expression \code{foo(bar(), baz)}.
This operation is safe if the squashed quosure is used for
labelling or printing (see \code{\link[=as_label]{as_label()}}, but note that \code{as_label()}
squashes quosures automatically). However if the squashed quosure
is evaluated, all expressions of the flattened quosures are
resolved in a single environment. This is a source of bugs so it is
good practice to set \code{warn} to \code{TRUE} to let the user know about
the lossy squashing.
}
\examples{
# Quosures can contain nested quosures:
quo <- quo(wrapper(!!quo(wrappee)))
quo
# quo_squash() flattens all the quosures and returns a simple expression:
quo_squash(quo)
}
rlang/man/get_env.Rd 0000644 0001762 0000144 00000005376 14175213516 014066 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env.R
\name{get_env}
\alias{get_env}
\alias{set_env}
\alias{env_poke_parent}
\title{Get or set the environment of an object}
\usage{
get_env(env, default = NULL)
set_env(env, new_env = caller_env())
env_poke_parent(env, new_env)
}
\arguments{
\item{env}{An environment.}
\item{default}{The default environment in case \code{env} does not wrap
an environment. If \code{NULL} and no environment could be extracted,
an error is issued.}
\item{new_env}{An environment to replace \code{env} with.}
}
\description{
These functions dispatch internally with methods for functions,
formulas and frames. If called with a missing argument, the
environment of the current evaluation frame is returned. If you
call \code{get_env()} with an environment, it acts as the identity
function and the environment is simply returned (this helps
simplifying code when writing generic functions for environments).
}
\details{
While \code{set_env()} returns a modified copy and does not have side
effects, \code{env_poke_parent()} operates changes the environment by
side effect. This is because environments are
\link[=is_copyable]{uncopyable}. Be careful not to change environments
that you don't own, e.g. a parent environment of a function from a
package.
}
\examples{
# Environment of closure functions:
fn <- function() "foo"
get_env(fn)
# Or of quosures or formulas:
get_env(~foo)
get_env(quo(foo))
# Provide a default in case the object doesn't bundle an environment.
# Let's create an unevaluated formula:
f <- quote(~foo)
# The following line would fail if run because unevaluated formulas
# don't bundle an environment (they didn't have the chance to
# record one yet):
# get_env(f)
# It is often useful to provide a default when you're writing
# functions accepting formulas as input:
default <- env()
identical(get_env(f, default), default)
# set_env() can be used to set the enclosure of functions and
# formulas. Let's create a function with a particular environment:
env <- child_env("base")
fn <- set_env(function() NULL, env)
# That function now has `env` as enclosure:
identical(get_env(fn), env)
identical(get_env(fn), current_env())
# set_env() does not work by side effect. Setting a new environment
# for fn has no effect on the original function:
other_env <- child_env(NULL)
set_env(fn, other_env)
identical(get_env(fn), other_env)
# Since set_env() returns a new function with a different
# environment, you'll need to reassign the result:
fn <- set_env(fn, other_env)
identical(get_env(fn), other_env)
}
\seealso{
\code{\link[=quo_get_env]{quo_get_env()}} and \code{\link[=quo_set_env]{quo_set_env()}} for versions of
\code{\link[=get_env]{get_env()}} and \code{\link[=set_env]{set_env()}} that only work on quosures.
}
rlang/man/as_name.Rd 0000644 0001762 0000144 00000003333 14175213516 014031 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/deparse.R
\name{as_name}
\alias{as_name}
\title{Extract names from symbols}
\usage{
as_name(x)
}
\arguments{
\item{x}{A string or symbol, possibly wrapped in a \link{quosure}.
If a string, the attributes are removed, if any.}
}
\value{
A character vector of length 1.
}
\description{
\code{as_name()} converts \link[=sym]{symbols} to character strings. The
conversion is deterministic. That is, the roundtrip \code{symbol -> name -> symbol} always gives the same result.
\itemize{
\item Use \code{as_name()} when you need to transform a symbol to a string
to \emph{refer} to an object by its name.
\item Use \code{\link[=as_label]{as_label()}} when you need to transform any kind of object to
a string to \emph{represent} that object with a short description.
}
Expect \code{as_name()} to gain
\href{https://principles.tidyverse.org/names-attribute.html#minimal-unique-universal}{name-repairing}
features in the future.
}
\details{
\code{rlang::as_name()} is the \emph{opposite} of \code{\link[base:name]{base::as.name()}}. If
you're writing base R code, we recommend using \code{\link[base:name]{base::as.symbol()}}
which is an alias of \code{as.name()} that follows a more modern
terminology (R types instead of S modes).
}
\examples{
# Let's create some symbols:
foo <- quote(foo)
bar <- sym("bar")
# as_name() converts symbols to strings:
foo
as_name(foo)
typeof(bar)
typeof(as_name(bar))
# as_name() unwraps quosured symbols automatically:
as_name(quo(foo))
}
\seealso{
\code{\link[=as_label]{as_label()}} for converting any object to a single string
suitable as a label. \code{\link[=as_string]{as_string()}} for a lower-level version that
doesn't unwrap quosures.
}
rlang/man/new-vector.Rd 0000644 0001762 0000144 00000002503 14175213516 014515 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vec-new.R
\name{new-vector}
\alias{new-vector}
\alias{new_logical}
\alias{new_integer}
\alias{new_double}
\alias{new_character}
\alias{new_complex}
\alias{new_raw}
\alias{new_list}
\title{Create vectors matching a given length}
\usage{
new_logical(n, names = NULL)
new_integer(n, names = NULL)
new_double(n, names = NULL)
new_character(n, names = NULL)
new_complex(n, names = NULL)
new_raw(n, names = NULL)
new_list(n, names = NULL)
}
\arguments{
\item{n}{The vector length.}
\item{names}{Names for the new vector.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#questioning}{\figure{lifecycle-questioning.svg}{options: alt='[Questioning]'}}}{\strong{[Questioning]}}
These functions construct vectors of a given length, with attributes
specified via dots. Except for \code{new_list()} and \code{new_raw()}, the
empty vectors are filled with typed \link{missing} values. This is in
contrast to the base function \code{\link[base:vector]{base::vector()}} which creates
zero-filled vectors.
}
\section{Lifecycle}{
These functions are likely to be replaced by a vctrs equivalent in
the future. They are in the questioning lifecycle stage.
}
\examples{
new_list(10)
new_logical(10)
}
\seealso{
rep_along
}
\keyword{internal}
rlang/man/topic-data-mask-programming.Rd 0000644 0001762 0000144 00000042402 14176517017 017730 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/topic-nse.R
\name{topic-data-mask-programming}
\alias{topic-data-mask-programming}
\title{Data mask programming patterns}
\description{
\link[=topic-data-mask]{Data-masking} functions require special programming patterns when used inside other functions. In this topic we'll review and compare the different patterns that can be used to solve specific problems.
If you are a beginner, you might want to start with one of these tutorials:
\itemize{
\item \href{https://dplyr.tidyverse.org/articles/programming.html}{Programming with dplyr}
\item \href{https://ggplot2.tidyverse.org/articles/ggplot2-in-packages.html}{Using ggplot2 in packages}
}
If you'd like to go further and learn about defusing and injecting expressions, read the \link[=topic-metaprogramming]{metaprogramming patterns topic}.
}
\section{Choosing a pattern}{
Two main considerations determine which programming pattern you need to wrap a data-masking function:
\enumerate{
\item What behaviour does the \emph{wrapped} function implement?
\item What behaviour should \emph{your} function implement?
}
Depending on the answers to these questions, you can choose between these approaches:
\itemize{
\item The \strong{forwarding patterns} with which your function inherits the behaviour of the function it interfaces with.
\item The \strong{name patterns} with which your function takes strings or character vectors of column names.
\item The \strong{bridge patterns} with which you change the behaviour of an argument instead of inheriting it.
}
You will also need to use different solutions for single named arguments than for multiple arguments in \code{...}.
}
\section{Argument behaviours}{
In a regular function, arguments can be defined in terms of a \emph{type} of objects that they accept. An argument might accept a character vector, a data frame, a single logical value, etc. Data-masked arguments are more complex. Not only do they generally accept a specific type of objects (for instance \code{dplyr::mutate()} accepts vectors), they exhibit special computational behaviours.
\itemize{
\item Data-masked expressions (base): E.g. \code{\link[=transform]{transform()}}, \code{\link[=with]{with()}}. Expressions may refer to the columns of the supplied data frame.
\item Data-masked expressions (tidy eval): E.g. \code{dplyr::mutate()}, \code{ggplot2::aes()}. Same as base data-masking but with tidy eval features enabled. This includes \link[=topic-inject]{injection operators} such as \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}} and \code{\link[=injection-operator]{!!}} and the \code{\link{.data}} and \code{\link{.env}} pronouns.
\item Data-masked symbols: Same as data-masked arguments but the supplied expressions must be simple column names. This often simplifies things, for instance this is an easy way of avoiding issues of \link[=topic-double-evaluation]{double evaluation}.
\item \href{https://tidyselect.r-lib.org/reference/language.html}{Tidy selections}: E.g. \code{dplyr::select()}, \code{tidyr::pivot_longer()}. This is an alternative to data masking that supports selection helpers like \code{starts_with()} or \code{all_of()}, and implements special behaviour for operators like \code{c()}, \code{|} and \code{&}.
Unlike data masking, tidy selection is an interpreted dialect. There is in fact no masking at all. Expressions are either interpreted in the context of the data frame (e.g. \code{c(cyl, am)} which stands for the union of the columns \code{cyl} and \code{am}), or evaluated in the user environment (e.g. \code{all_of()}, \code{starts_with()}, and any other expressions). This has implications for inheritance of argument behaviour as we will see below.
\item \link[=doc_dots_dynamic]{Dynamic dots}: These may be data-masked arguments, tidy selections, or just regular arguments. Dynamic dots support injection of multiple arguments with the \code{\link[=splice-operator]{!!!}} operator as well as name injection with \link[=glue-operators]{glue} operators.
}
To let users know about the capabilities of your function arguments, document them with the following tags, depending on which set of semantics they inherit from:\preformatted{@param foo <[`data-masked`][dplyr::dplyr_data_masking]> What `foo` does.
@param bar <[`tidy-select`][dplyr::dplyr_tidy_select]> What `bar` does.
@param ... <[`dynamic-dots`][rlang::dyn-dots]> What these dots do.
}
}
\section{Forwarding patterns}{
With the forwarding patterns, arguments inherit the behaviour of the data-masked arguments they are passed in.
\subsection{Embrace with \verb{\{\{}}{
The embrace operator \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}} is a forwarding syntax for single arguments. You can forward an argument in data-masked context:\if{html}{\out{
}}\preformatted{my_summarise <- function(data, var) \{
data \%>\% dplyr::summarise(\{\{ var \}\})
\}
}\if{html}{\out{
}}
Or in tidyselections:\if{html}{\out{
}}\preformatted{my_pivot_longer <- function(data, var) \{
data \%>\% tidyr::pivot_longer(cols = \{\{ var \}\})
\}
}\if{html}{\out{
}}
The function automatically inherits the behaviour of the surrounding context. For instance arguments forwarded to a data-masked context may refer to columns or use the \code{\link{.data}} pronoun:\if{html}{\out{
}}\preformatted{mtcars \%>\% my_summarise(mean(cyl))
x <- "cyl"
mtcars \%>\% my_summarise(mean(.data[[x]]))
}\if{html}{\out{
}}
And arguments forwarded to a tidy selection may use all tidyselect features:\if{html}{\out{
}}
}
\subsection{Forward \code{...}}{
Simple forwarding of \code{...} arguments does not require any special syntax since dots are already a forwarding syntax. Just pass them to another function like you normally would. This works with data-masked arguments:\if{html}{\out{
}}
Inside a tidy selection, \code{c()} is not a vector concatenator but a selection combinator. This makes it handy to interface between functions that take \code{...} and functions that take a single argument.
}
}
\section{Names patterns}{
With the names patterns you refer to columns by name with strings or character vectors stored in env-variables. Whereas the forwarding patterns are exclusively used within a function to pass \emph{arguments}, the names patterns can be used anywhere.
\itemize{
\item In a script, you can loop over a character vector with \code{for} or \code{lapply()} and use the \code{\link{.data}} pattern to connect a name to its data-variable. A vector can also be supplied all at once to the tidy select helper \code{all_of()}.
\item In a function, using the names patterns on function arguments lets users supply regular data-variable names without any of the complications that come with data-masking.
}
\subsection{Subsetting the \code{.data} pronoun}{
The \code{\link{.data}} pronoun is a tidy eval feature that is enabled in all data-masked arguments, just like \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}}. The pronoun represents the data mask and can be subsetted with \code{[[} and \code{$}. These three statements are equivalent:\if{html}{\out{
}}
The \code{.data} pronoun can be subsetted in loops:\if{html}{\out{
}}\preformatted{vars <- c("cyl", "am")
for (var in vars) print(dplyr::summarise(mtcars, mean = mean(.data[[var]])))
#> # A tibble: 1 x 1
#> mean
#>
#> 1 6.19
#> # A tibble: 1 x 1
#> mean
#>
#> 1 0.406
purrr::map(vars, ~ dplyr::summarise(mtcars, mean = mean(.data[[.x]])))
#> [[1]]
#> # A tibble: 1 x 1
#> mean
#>
#> 1 6.19
#>
#> [[2]]
#> # A tibble: 1 x 1
#> mean
#>
#> 1 0.406
}\if{html}{\out{
}}
And it can be used to connect function arguments to a data-variable:\if{html}{\out{
}}\preformatted{my_mean <- function(data, var) \{
data \%>\% dplyr::summarise(mean = mean(.data[[var]]))
\}
my_mean(mtcars, "cyl")
#> # A tibble: 1 x 1
#> mean
#>
#> 1 6.19
}\if{html}{\out{
}}
With this implementation, \code{my_mean()} is completely insulated from data-masking behaviour and is called like an ordinary function.\if{html}{\out{
}}\preformatted{# No masking
am <- "cyl"
my_mean(mtcars, am)
#> # A tibble: 1 x 1
#> mean
#>
#> 1 6.19
# Programmable
my_mean(mtcars, tolower("CYL"))
#> # A tibble: 1 x 1
#> mean
#>
#> 1 6.19
}\if{html}{\out{
}}
}
\subsection{Character vector of names}{
The \code{.data} pronoun can only be subsetted with single column names. It doesn't support single-bracket indexing:\if{html}{\out{
}}\preformatted{mtcars \%>\% dplyr::summarise(.data[c("cyl", "am")])
#> Error in `dplyr::summarise()`:
#> ! Problem while computing `..1 = .data[c("cyl", "am")]`.
#> Caused by error in `.data[c("cyl", "am")]`:
#> ! `[` is not supported by the `.data` pronoun, use `[[` or $ instead.
}\if{html}{\out{
}}
There is no plural variant of \code{.data} built in tidy eval. Instead, we'll used the \code{all_of()} operator available in tidy selections to supply character vectors. This is straightforward in functions that take tidy selections, like \code{tidyr::pivot_longer()}:\if{html}{\out{
}}\preformatted{vars <- c("cyl", "am")
mtcars \%>\% tidyr::pivot_longer(all_of(vars))
#> # A tibble: 64 x 11
#> mpg disp hp drat wt qsec vs gear carb name value
#>
#> 1 21 160 110 3.9 2.62 16.5 0 4 4 cyl 6
#> 2 21 160 110 3.9 2.62 16.5 0 4 4 am 1
#> 3 21 160 110 3.9 2.88 17.0 0 4 4 cyl 6
#> 4 21 160 110 3.9 2.88 17.0 0 4 4 am 1
#> # ... with 60 more rows
}\if{html}{\out{
}}
If the function does not take a tidy selection, it might be possible to use a \emph{bridge pattern}. This option is presented in the bridge section below. If a bridge is impossible or inconvenient, a little metaprogramming with the \link[=topic-metaprogramming]{symbolise-and-inject pattern} can help.
}
}
\section{Bridge patterns}{
Sometimes the function you are calling does not implement the behaviour you would like to give to the arguments of your function. To work around this may require a little thought since there is no systematic way of turning one behaviour into another. The general technique consists in forwarding the arguments inside a context that implements the behaviour that you want. Then, find a way to bridge the result to the target verb or function.
\subsection{\code{across()} as a selection to data-mask bridge}{
dplyr 1.0 added support for tidy selections in all verbs via \code{across()}. This function is normally used for mapping over columns but can also be used to perform a simple selection. For instance, if you'd like to pass an argument to \code{group_by()} with a tidy-selection interface instead of a data-masked one, use \code{across()} as a bridge:\if{html}{\out{
}}\preformatted{my_group_by <- function(data, var) \{
data \%>\% dplyr::group_by(across(\{\{ var \}\}))
\}
mtcars \%>\% my_group_by(starts_with("c"))
}\if{html}{\out{
}}
Since \code{across()} takes selections in a single argument (unlike \code{select()} which takes multiple arguments), you can't directly pass \code{...}. Instead, take them within \code{c()}, which is the tidyselect way of supplying multiple selections within a single argument:\if{html}{\out{
}}
}
\subsection{\code{across(all_of())} as a names to data mask bridge}{
If instead of forwarding variables in \code{across()} you pass them to \code{all_of()}, you create a names to data mask bridge.\if{html}{\out{
}}
Use this bridge technique to connect vectors of names to a data-masked context.
}
\subsection{\code{transmute()} as a data-mask to selection bridge}{
Passing data-masked arguments to a tidy selection is a little more tricky and requires a three step process.\if{html}{\out{
}}\preformatted{my_pivot_longer <- function(data, ...) \{
# Forward `...` in data-mask context with `transmute()`
# and save the inputs names
inputs <- dplyr::transmute(data, ...)
names <- names(inputs)
# Update the data with the inputs
data <- dplyr::mutate(data, !!!inputs)
# Select the inputs by name with `all_of()`
tidyr::pivot_longer(data, cols = all_of(names))
\}
mtcars \%>\% my_pivot_longer(cyl, am = am * 100)
}\if{html}{\out{
}}
\enumerate{
\item In a first step we pass the \code{...} expressions to \code{transmute()}. Unlike \code{mutate()}, it creates a new data frame from the user inputs. The only goal of this step is to inspect the names in \code{...}, including the default names created for unnamed arguments.
\item Once we have the names, we inject the arguments into \code{mutate()} to update the data frame.
\item Finally, we pass the names to the tidy selection via \href{https://tidyselect.r-lib.org/reference/all_of.html}{\code{all_of()}}.
}
}
}
\section{Transformation patterns}{
\subsection{Named inputs versus \code{...}}{
In the case of a named argument, transformation is easy. We simply surround the embraced input it in R code. For instance, the \code{my_summarise()} function is not exactly useful compared to just calling \code{summarise()}:\if{html}{\out{
}}\preformatted{my_summarise <- function(data, var) \{
data \%>\% dplyr::summarise(\{\{ var \}\})
\}
}\if{html}{\out{
}}
We can make it more useful by adding code around the variable:\if{html}{\out{
}}\preformatted{my_mean <- function(data, var) \{
data \%>\% dplyr::summarise(mean = mean(\{\{ var \}\}, na.rm = TRUE))
\}
}\if{html}{\out{
}}
For inputs in \code{...} however, this technique does not work. We would need some kind of templating syntax for dots that lets us specify R code with a placeholder for the dots elements. This isn't built in tidy eval but you can use operators like \code{dplyr::across()}, \code{dplyr::if_all()}, or \code{dplyr::if_any()}. When that isn't possible, you can template the expression manually.
}
\subsection{Transforming inputs with \code{across()}}{
The \code{across()} operation in dplyr is a convenient way of mapping an expression across a set of inputs. We will create a variant of \code{my_mean()} that computes the \code{mean()} of all arguments supplied in \code{...}. The easiest way it to forward the dots to \code{across()} (which causes \code{...} to inherit its tidy selection behaviour):\if{html}{\out{
}}\preformatted{my_mean <- function(data, ...) \{
data \%>\% dplyr::summarise(across(c(...), ~ mean(.x, na.rm = TRUE)))
\}
mtcars \%>\% my_mean(cyl, carb)
#> # A tibble: 1 x 2
#> cyl carb
#>
#> 1 6.19 2.81
mtcars \%>\% my_mean(foo = cyl, bar = carb)
#> # A tibble: 1 x 2
#> foo bar
#>
#> 1 6.19 2.81
mtcars \%>\% my_mean(starts_with("c"), mpg:disp)
#> # A tibble: 1 x 4
#> cyl carb mpg disp
#>
#> 1 6.19 2.81 20.1 231.
}\if{html}{\out{
}}
}
\subsection{Transforming inputs with \code{if_all()} and \code{if_any()}}{
\code{dplyr::filter()} requires a different operation than \code{across()} because it needs to combine the logical expressions with \code{&} or \code{|}. To solve this problem dplyr introduced the \code{if_all()} and \code{if_any()} variants of \code{across()}.
In the following example, we filter all rows for which a set of variables are not equal to their minimum value:\if{html}{\out{
}}
}
}
\keyword{internal}
rlang/man/exec.Rd 0000644 0001762 0000144 00000003156 14140204504 013342 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/eval.R
\name{exec}
\alias{exec}
\title{Execute a function}
\usage{
exec(.fn, ..., .env = caller_env())
}
\arguments{
\item{.fn}{A function, or function name as a string.}
\item{...}{<\link[=dyn-dots]{dynamic}> Arguments for \code{.fn}.}
\item{.env}{Environment in which to evaluate the call. This will be
most useful if \code{f} is a string, or the function has side-effects.}
}
\description{
This function constructs and evaluates a call to \code{.fn}.
It has two primary uses:
\itemize{
\item To call a function with arguments stored in a list (if the
function doesn't support \link[=dyn-dots]{dynamic dots}). Splice the
list of arguments with \verb{!!!}.
\item To call every function stored in a list (in conjunction with \code{map()}/
\code{\link[=lapply]{lapply()}})
}
}
\examples{
args <- list(x = c(1:10, 100, NA), na.rm = TRUE)
exec("mean", !!!args)
exec("mean", !!!args, trim = 0.2)
fs <- list(a = function() "a", b = function() "b")
lapply(fs, exec)
# Compare to do.call it will not automatically inline expressions
# into the evaluated call.
x <- 10
args <- exprs(x1 = x + 1, x2 = x * 2)
exec(list, !!!args)
do.call(list, args)
# exec() is not designed to generate pretty function calls. This is
# most easily seen if you call a function that captures the call:
f <- disp ~ cyl
exec("lm", f, data = mtcars)
# If you need finer control over the generated call, you'll need to
# construct it yourself. This may require creating a new environment
# with carefully constructed bindings
data_env <- env(data = mtcars)
eval(expr(lm(!!f, data)), data_env)
}
rlang/man/eval_bare.Rd 0000644 0001762 0000144 00000007307 14175213516 014353 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/eval.R
\name{eval_bare}
\alias{eval_bare}
\title{Evaluate an expression in an environment}
\usage{
eval_bare(expr, env = parent.frame())
}
\arguments{
\item{expr}{An expression to evaluate.}
\item{env}{The environment in which to evaluate the expression.}
}
\description{
\code{eval_bare()} is a lower-level version of function \code{\link[base:eval]{base::eval()}}.
Technically, it is a simple wrapper around the C function
\code{Rf_eval()}. You generally don't need to use \code{eval_bare()} instead
of \code{eval()}. Its main advantage is that it handles stack-sensitive
calls (such as \code{return()}, \code{on.exit()} or \code{parent.frame()}) more
consistently when you pass an enviroment of a frame on the call
stack.
}
\details{
These semantics are possible because \code{eval_bare()} creates only one
frame on the call stack whereas \code{eval()} creates two frames, the
second of which has the user-supplied environment as frame
environment. When you supply an existing frame environment to
\code{base::eval()} there will be two frames on the stack with the same
frame environment. Stack-sensitive functions only detect the
topmost of these frames. We call these evaluation semantics
"stack inconsistent".
Evaluating expressions in the actual frame environment has useful
practical implications for \code{eval_bare()}:
\itemize{
\item \code{return()} calls are evaluated in frame environments that might
be burried deep in the call stack. This causes a long return that
unwinds multiple frames (triggering the \code{on.exit()} event for
each frame). By contrast \code{eval()} only returns from the \code{eval()}
call, one level up.
\item \code{on.exit()}, \code{parent.frame()}, \code{sys.call()}, and generally all
the stack inspection functions \code{sys.xxx()} are evaluated in the
correct frame environment. This is similar to how this type of
calls can be evaluated deep in the call stack because of lazy
evaluation, when you force an argument that has been passed
around several times.
}
The flip side of the semantics of \code{eval_bare()} is that it can't
evaluate \code{break} or \code{next} expressions even if called within a
loop.
}
\examples{
# eval_bare() works just like base::eval() but you have to create
# the evaluation environment yourself:
eval_bare(quote(foo), env(foo = "bar"))
# eval() has different evaluation semantics than eval_bare(). It
# can return from the supplied environment even if its an
# environment that is not on the call stack (i.e. because you've
# created it yourself). The following would trigger an error with
# eval_bare():
ret <- quote(return("foo"))
eval(ret, env())
# eval_bare(ret, env()) # "no function to return from" error
# Another feature of eval() is that you can control surround loops:
bail <- quote(break)
while (TRUE) {
eval(bail)
# eval_bare(bail) # "no loop for break/next" error
}
# To explore the consequences of stack inconsistent semantics, let's
# create a function that evaluates `parent.frame()` deep in the call
# stack, in an environment corresponding to a frame in the middle of
# the stack. For consistency with R's lazy evaluation semantics, we'd
# expect to get the caller of that frame as result:
fn <- function(eval_fn) {
list(
returned_env = middle(eval_fn),
actual_env = current_env()
)
}
middle <- function(eval_fn) {
deep(eval_fn, current_env())
}
deep <- function(eval_fn, eval_env) {
expr <- quote(parent.frame())
eval_fn(expr, eval_env)
}
# With eval_bare(), we do get the expected environment:
fn(rlang::eval_bare)
# But that's not the case with base::eval():
fn(base::eval)
}
\seealso{
\code{\link[=eval_tidy]{eval_tidy()}} for evaluation with data mask and quosure
support.
}
rlang/man/new_node.Rd 0000644 0001762 0000144 00000003426 14137447476 014243 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/node.R
\name{new_node}
\alias{new_node}
\alias{node_car}
\alias{node_cdr}
\alias{node_caar}
\alias{node_cadr}
\alias{node_cdar}
\alias{node_cddr}
\alias{node_poke_car}
\alias{node_poke_cdr}
\alias{node_poke_caar}
\alias{node_poke_cadr}
\alias{node_poke_cdar}
\alias{node_poke_cddr}
\alias{node_tag}
\alias{node_poke_tag}
\title{Helpers for pairlist and language nodes}
\usage{
new_node(car, cdr = NULL)
node_car(x)
node_cdr(x)
node_caar(x)
node_cadr(x)
node_cdar(x)
node_cddr(x)
node_poke_car(x, newcar)
node_poke_cdr(x, newcdr)
node_poke_caar(x, newcar)
node_poke_cadr(x, newcar)
node_poke_cdar(x, newcdr)
node_poke_cddr(x, newcdr)
node_tag(x)
node_poke_tag(x, newtag)
}
\arguments{
\item{car, newcar, cdr, newcdr}{The new CAR or CDR for the node. These
can be any R objects.}
\item{x}{A language or pairlist node. Note that these functions are
barebones and do not perform any type checking.}
\item{newtag}{The new tag for the node. This should be a symbol.}
}
\value{
Setters like \code{node_poke_car()} invisibly return \code{x} modified
in place. Getters return the requested node component.
}
\description{
\strong{Important}: These functions are for expert R programmers only.
You should only use them if you feel comfortable manipulating low
level R data structures at the C level. We export them at the R level
in order to make it easy to prototype C code. They don't perform
any type checking and can crash R very easily (try to take the CAR
of an integer vector --- save any important objects beforehand!).
}
\seealso{
\code{\link[=duplicate]{duplicate()}} for creating copy-safe objects and
\code{\link[base:list]{base::pairlist()}} for an easier way of creating a linked list of
nodes.
}
\keyword{internal}
rlang/man/is_installed.Rd 0000644 0001762 0000144 00000007110 14175213516 015075 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/session.R
\name{is_installed}
\alias{is_installed}
\alias{check_installed}
\title{Are packages installed in any of the libraries?}
\usage{
is_installed(pkg, ..., version = NULL, compare = NULL)
check_installed(
pkg,
reason = NULL,
...,
version = NULL,
compare = NULL,
action = NULL,
call = caller_env()
)
}
\arguments{
\item{pkg}{The package names. Can include version requirements,
e.g. \code{"pkg (>= 1.0.0)"}.}
\item{...}{These dots must be empty.}
\item{version}{Minimum versions for \code{pkg}. If supplied, must be the
same length as \code{pkg}. \code{NA} elements stand for any versions.}
\item{compare}{A character vector of comparison operators to use
for \code{version}. If supplied, must be the same length as
\code{version}. If \code{NULL}, \code{>=} is used as default for all
elements. \code{NA} elements in \code{compare} are also set to \code{>=} by
default.}
\item{reason}{Optional string indicating why is \code{pkg} needed.
Appears in error messages (if non-interactive) and user prompts
(if interactive).}
\item{action}{An optional function taking \code{pkg} and \code{...}
arguments. It is called by \code{check_installed()} when the user
chooses to update outdated packages. The function is passed the
missing and outdated packages as a character vector of names.}
\item{call}{The execution environment of a currently
running function, e.g. \code{caller_env()}. The function will be
mentioned in error messages as the source of the error. See the
\code{call} argument of \code{\link[=abort]{abort()}} for more information.}
}
\value{
\code{is_installed()} returns \code{TRUE} if \emph{all} package names
provided in \code{pkg} are installed, \code{FALSE}
otherwise. \code{check_installed()} either doesn't return or returns
\code{NULL}.
}
\description{
These functions check that packages are installed with minimal side
effects. If installed, the packages will be loaded but not
attached.
\itemize{
\item \code{is_installed()} doesn't interact with the user. It simply
returns \code{TRUE} or \code{FALSE} depending on whether the packages are
installed.
\item In interactive sessions, \code{check_installed()} asks the user
whether to install missing packages. If the user accepts, the
packages are installed with \code{pak::pkg_install()} if available, or
\code{\link[utils:install.packages]{utils::install.packages()}} otherwise. If the session is non
interactive or if the user chooses not to install the packages,
the current evaluation is aborted.
}
You can disable the prompt by setting the
\code{rlib_restart_package_not_found} global option to \code{FALSE}. In that
case, missing packages always cause an error.
}
\section{Handling package not found errors}{
\code{check_installed()} signals error conditions of class
\code{rlib_error_package_not_found}. The error includes \code{pkg} and
\code{version} fields. They are vectorised and may include several
packages.
The error is signalled with a \code{rlib_restart_package_not_found}
restart on the stack to allow handlers to install the required
packages. To do so, add a \link[=withCallingHandlers]{calling handler}
for \code{rlib_error_package_not_found}, install the required packages,
and invoke the restart without arguments. This restarts the check
from scratch.
The condition is not signalled in non-interactive sessions, in the
restarting case, or if the \code{rlib_restart_package_not_found} user
option is set to \code{FALSE}.
}
\examples{
is_installed("utils")
is_installed(c("base", "ggplot5"))
is_installed(c("base", "ggplot5"), version = c(NA, "5.1.0"))
}
rlang/man/parse_expr.Rd 0000644 0001762 0000144 00000006222 14127057575 014606 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/parse.R
\name{parse_expr}
\alias{parse_expr}
\alias{parse_exprs}
\alias{parse_quo}
\alias{parse_quos}
\title{Parse R code}
\usage{
parse_expr(x)
parse_exprs(x)
parse_quo(x, env = global_env())
parse_quos(x, env = global_env())
}
\arguments{
\item{x}{Text containing expressions to parse_expr for
\code{parse_expr()} and \code{parse_exprs()}. Can also be an R connection,
for instance to a file. If the supplied connection is not open,
it will be automatically closed and destroyed.}
\item{env}{The environment for the quosures. The \link[=global_env]{global environment} (the default) may be the right choice
when you are parsing external user inputs. You might also want to
evaluate the R code in an isolated context (perhaps a child of
the global environment or of the \link[=base_env]{base environment}).}
}
\value{
\code{parse_expr()} returns an \link[=is_expression]{expression},
\code{parse_exprs()} returns a list of expressions. Note that for the
plural variants the length of the output may be greater than the
length of the input. This would happen is one of the strings
contain several expressions (such as \code{"foo; bar"}). The names of
\code{x} are preserved (and recycled in case of multiple expressions).
The \verb{_quo} suffixed variants return quosures.
}
\description{
These functions parse and transform text into R expressions. This
is the first step to interpret or evaluate a piece of R code
written by a programmer.
\itemize{
\item \code{parse_expr()} returns one expression. If the text contains more
than one expression (separated by semicolons or new lines), an
error is issued. On the other hand \code{parse_exprs()} can handle
multiple expressions. It always returns a list of expressions
(compare to \code{\link[base:parse]{base::parse()}} which returns a base::expression
vector). All functions also support R connections.
\item \code{parse_quo()} and \code{parse_quos()} are variants that create a
\link[=quo]{quosure} that inherits from the global environment by
default. This is appropriate when you're parsing external user
input to be evaluated in user context (rather than the private
contexts of your functions).
Unlike quosures created with \code{\link[=enquo]{enquo()}}, \code{\link[=enquos]{enquos()}}, or \verb{\{\{}, a
parsed quosure never contains injected quosures. It is thus safe
to evaluate them with \code{eval()} instead of \code{\link[=eval_tidy]{eval_tidy()}}, though
the latter is more convenient as you don't need to extract \code{expr}
and \code{env}.
}
}
\examples{
# parse_expr() can parse any R expression:
parse_expr("mtcars \%>\% dplyr::mutate(cyl_prime = cyl / sd(cyl))")
# A string can contain several expressions separated by ; or \n
parse_exprs("NULL; list()\n foo(bar)")
# Use names to figure out which input produced an expression:
parse_exprs(c(foo = "1; 2", bar = "3"))
# You can also parse source files by passing a R connection. Let's
# create a file containing R code:
path <- tempfile("my-file.R")
cat("1; 2; mtcars", file = path)
# We can now parse it by supplying a connection:
parse_exprs(file(path))
}
\seealso{
\code{\link[base:parse]{base::parse()}}
}
rlang/man/env_bury.Rd 0000644 0001762 0000144 00000003325 14175213516 014260 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-superseded.R
\name{env_bury}
\alias{env_bury}
\title{Mask bindings by defining symbols deeper in a scope}
\usage{
env_bury(.env, ...)
}
\arguments{
\item{.env}{An environment.}
\item{...}{<\link[=dyn-dots]{dynamic}> Named objects (\code{env_bind()}),
expressions \code{env_bind_lazy()}, or functions (\code{env_bind_active()}).
Use \code{\link[=zap]{zap()}} to remove bindings.}
}
\value{
A copy of \code{.env} enclosing the new environment containing
bindings to \code{...} arguments.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#superseded}{\figure{lifecycle-superseded.svg}{options: alt='[Superseded]'}}}{\strong{[Superseded]}}
This function is superseded. Please use \code{\link[=env]{env()}} (and possibly
\code{\link[=set_env]{set_env()}} if you're masking the bindings for another object like
a closure or a formula) instead.
\code{env_bury()} is like \code{\link[=env_bind]{env_bind()}} but it creates the bindings in a
new child environment. This makes sure the new bindings have
precedence over old ones, without altering existing environments.
Unlike \code{env_bind()}, this function does not have side effects and
returns a new environment (or object wrapping that environment).
}
\examples{
orig_env <- env(a = 10)
fn <- set_env(function() a, orig_env)
# fn() currently sees `a` as the value `10`:
fn()
# env_bury() will bury the current scope of fn() behind a new
# environment:
fn <- env_bury(fn, a = 1000)
fn()
# Even though the symbol `a` is still defined deeper in the scope:
orig_env$a
}
\seealso{
\code{\link[=env_bind]{env_bind()}}, \code{\link[=env_unbind]{env_unbind()}}
}
\keyword{internal}
rlang/man/env_unlock.Rd 0000644 0001762 0000144 00000000574 13351410763 014573 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env.R
\name{env_unlock}
\alias{env_unlock}
\title{Unlock an environment}
\usage{
env_unlock(env)
}
\arguments{
\item{env}{An environment.}
}
\value{
Whether the environment has been unlocked.
}
\description{
This function should only be used in development tools or
interactively.
}
\keyword{internal}
rlang/man/dyn-dots.Rd 0000644 0001762 0000144 00000003510 14175213516 014164 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dots.R
\name{dyn-dots}
\alias{dyn-dots}
\alias{tidy-dots}
\alias{doc_dots_dynamic}
\alias{:=}
\title{Dynamic dots features}
\description{
The base \code{...} syntax supports:
\itemize{
\item \strong{Forwarding} arguments from function to function, matching them
along the way to arguments.
\item \strong{Collecting} arguments inside data structures, e.g. with \code{\link[=c]{c()}} or
\code{\link[=list]{list()}}.
}
Dynamic dots offer a few additional features,
\link[=topic-inject]{injection} in particular:
\enumerate{
\item You can \strong{splice} arguments saved in a list with the splice
operator \code{\link[=splice-operator]{!!!}}.
\item You can \strong{inject} names with \link[=glue-operators]{glue syntax} on
the left-hand side of \verb{:=}.
\item Trailing commas are ignored, making it easier to copy and paste
lines of arguments.
}
}
\section{Add dynamic dots support in your functions}{
If your function takes dots, adding support for dynamic features is
as easy as collecting the dots with \code{\link[=list2]{list2()}} instead of \code{\link[=list]{list()}}.
See also \code{\link[=dots_list]{dots_list()}}, which offers more control over the collection.
In general, passing \code{...} to a function that supports dynamic dots
causes your function to inherit the dynamic behaviour.
In packages, document dynamic dots with this standard tag:\preformatted{ @param ... <[`dynamic-dots`][rlang::dyn-dots]> What these dots do.
}
}
\examples{
f <- function(...) {
out <- list2(...)
rev(out)
}
# Trailing commas are ignored
f(this = "that", )
# Splice lists of arguments with `!!!`
x <- list(alpha = "first", omega = "last")
f(!!!x)
# Inject a name using glue syntax
if (is_installed("glue")) {
nm <- "key"
f("{nm}" := "value")
f("prefix_{nm}" := "value")
}
}
rlang/man/abort.Rd 0000644 0001762 0000144 00000026621 14176514055 013545 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-abort.R, R/cnd-signal.R
\name{abort}
\alias{abort}
\alias{warn}
\alias{inform}
\alias{signal}
\title{Signal an error, warning, or message}
\usage{
abort(
message = NULL,
class = NULL,
...,
call,
body = NULL,
footer = NULL,
trace = NULL,
parent = NULL,
use_cli_format = NULL,
.internal = FALSE,
.file = NULL,
.frame = NULL,
.subclass = deprecated()
)
warn(
message = NULL,
class = NULL,
...,
body = NULL,
footer = NULL,
use_cli_format = NULL,
.frequency = c("always", "regularly", "once"),
.frequency_id = NULL,
.subclass = deprecated()
)
inform(
message = NULL,
class = NULL,
...,
body = NULL,
footer = NULL,
use_cli_format = NULL,
.file = NULL,
.frequency = c("always", "regularly", "once"),
.frequency_id = NULL,
.subclass = deprecated()
)
signal(message, class, ..., .subclass = deprecated())
}
\arguments{
\item{message}{The message to display, formatted as a \strong{bulleted
list}. The first element is displayed as an \emph{alert} bullet
prefixed with \code{!} by default. Elements named \code{"*"}, \code{"i"}, and
\code{"x"} are formatted as regular, info, and cross bullets
respectively. Se\ifelse{html}{\link[=topic-condition-formatting]{Formatting condition messages}}{\link[=topic-condition-formatting]{Formatting condition messages}})` for more
about bulleted messaging.
If a message is not supplied, it is expected that the message is
generated \strong{lazily} through \code{\link[=cnd_header]{cnd_header()}} and \code{\link[=cnd_body]{cnd_body()}}
methods. In that case, \code{class} must be supplied. Only \code{inform()}
allows empty messages as it is occasionally useful to build user
output incrementally.}
\item{class}{Subclass of the condition.}
\item{...}{Additional data to be stored in the condition object.
If you supply condition fields, you should usually provide a
\code{class} argument. You may consider prefixing condition fields
with the name of your package or organisation to prevent name
collisions.}
\item{call}{The execution environment of a currently running
function, e.g. \code{call = caller_env()}. The corresponding function
call is retrieved and mentioned in error messages as the source
of the error.
You only need to supply \code{call} when throwing a condition from a
helper function which wouldn't be relevant to mention in the
message.
Can also be \code{NULL} or a \link[=topic-defuse]{defused function call} to
respectively not display any call or hard-code a code to display.}
\item{body, footer}{Additional bullets.}
\item{trace}{A \code{trace} object created by \code{\link[=trace_back]{trace_back()}}.}
\item{parent}{Supply \code{parent} when you rethrow an error from a
condition handler (e.g. with \code{\link[=try_fetch]{try_fetch()}}).
\itemize{
\item If \code{parent} is a condition object, a \emph{chained error} is
created, which is useful when you want to enhance an error with
more details, while still retaining the original information.
\item If \code{parent} is \code{NA}, it indicates an unchained rethrow, which
is useful when you want to take ownership over an error and
rethrow it with a custom message that better fits the
surrounding context.
Technically, supplying \code{NA} lets \code{abort()} know it is called
from a condition handler. This helps it create simpler
backtraces where the condition handling context is hidden by
default.
}}
\item{use_cli_format}{Whether to format \code{message} lazily using
\href{https://cli.r-lib.org/}{cli} if available. This results in
prettier and more accurate formatting of messages. See
\code{\link[=local_use_cli]{local_use_cli()}} to set this condition field by default in your
package namespace.
If set to \code{TRUE}, \code{message} should be a character vector of
individual and unformatted lines. Any newline character \code{"\\\\n"}
already present in \code{message} is reformatted by cli's paragraph
formatter. See \ifelse{html}{\link[=topic-condition-formatting]{Formatting condition messages}}{\link[=topic-condition-formatting]{Formatting condition messages}}.}
\item{.internal}{If \code{TRUE}, a footer bullet is added to \code{message}
to let the user know that the error is internal and that they
should report it to the package authors. This argument is
incompatible with \code{footer}.}
\item{.file}{A connection or a string specifying where to print the
message. The default depends on the context, see the \code{stdout} vs
\code{stderr} section.}
\item{.frame}{The throwing context. Defaults to \code{call} if it is an
environment, \code{\link[=caller_env]{caller_env()}} otherwise. This is used in the
display of simplified backtraces as the last relevant call frame
to show. This way, the irrelevant parts of backtraces
corresponding to condition handling (\code{\link[=tryCatch]{tryCatch()}}, \code{\link[=try_fetch]{try_fetch()}},
\code{abort()}, etc.) are hidden by default.}
\item{.subclass}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} This argument
was renamed to \code{class} in rlang 0.4.2 for consistency with our
conventions for class constructors documented in
\url{https://adv-r.hadley.nz/s3.html#s3-subclassing}.}
\item{.frequency}{How frequently should the warning or message be
displayed? By default (\code{"always"}) it is displayed at each
time. If \code{"regularly"}, it is displayed once every 8 hours. If
\code{"once"}, it is displayed once per session.}
\item{.frequency_id}{A unique identifier for the warning or
message. This is used when \code{.frequency} is supplied to recognise
recurring conditions. This argument must be supplied if
\code{.frequency} is not set to \code{"always"}.}
}
\description{
These functions are equivalent to base functions \code{\link[base:stop]{base::stop()}},
\code{\link[base:warning]{base::warning()}}, and \code{\link[base:message]{base::message()}}. They signal a condition
(an error, warning, or message respectively) and make it easy to
supply condition metadata:
\itemize{
\item Supply \code{class} to create a classed condition that can be caught
or handled selectively, allowing for finer-grained error
handling.
\item Supply metadata with named \code{...} arguments. This data is stored
in the condition object and can be examined by handlers.
\item Supply \code{call} to inform users about which function the error
occurred in.
\item Supply another condition as \code{parent} to create a chained
condition.
}
Certain components of condition messages are formatted with unicode
symbols and terminal colours by default. These aspects can be
customised, see \ifelse{html}{\link[=topic-condition-customisation]{Customising condition messages}}{\link[=topic-condition-customisation]{Customising condition messages}}.
}
\details{
\itemize{
\item \code{abort()} throws subclassed errors, see
\code{\link[=rlang_error]{"rlang_error"}}.
\item \code{warn()} temporarily set the \code{warning.length} global option to
the maximum value (8170), unless that option has been changed
from the default value. The default limit (1000 characters) is
especially easy to hit when the message contains a lot of ANSI
escapes, as created by the crayon or cli packages
}
}
\section{Error prefix}{
As with \code{\link[base:stop]{base::stop()}}, errors thrown with \code{abort()} are prefixed
with \code{"Error: "}. Calls and source references are included in the
prefix, e.g. \verb{"Error in }my_function()\verb{ at myfile.R:1:2:"}. There
are a few cosmetic differences:
\itemize{
\item The call is stripped from its arguments to keep it simple. It is
then formatted using the \href{https://cli.r-lib.org/}{cli package} if
available.
\item A line break between the prefix and the message when the former
is too long. When a source location is included, a line break is
always inserted.
}
If your throwing code is highly structured, you may have to
explicitly inform \code{abort()} about the relevant user-facing call to
include in the prefix. Internal helpers are rarely relevant to end
users. See the \code{call} argument of \code{abort()}.
}
\section{Backtrace}{
\code{abort()} saves a backtrace in the \code{trace} component of the error
condition. You can print a simplified backtrace of the last error
by calling \code{\link[=last_error]{last_error()}} and a full backtrace with
\code{summary(last_error())}. Learn how to control what is displayed
when an error is thrown with \code{\link{rlang_backtrace_on_error}}.
}
\section{Muffling and silencing conditions}{
Signalling a condition with \code{inform()} or \code{warn()} displays a
message in the console. These messages can be muffled as usual with
\code{\link[base:message]{base::suppressMessages()}} or \code{\link[base:warning]{base::suppressWarnings()}}.
\code{inform()} and \code{warn()} messages can also be silenced with the
global options \code{rlib_message_verbosity} and
\code{rlib_warning_verbosity}. These options take the values:
\itemize{
\item \code{"default"}: Verbose unless the \code{.frequency} argument is supplied.
\item \code{"verbose"}: Always verbose.
\item \code{"quiet"}: Always quiet.
}
When set to quiet, the message is not displayed and the condition
is not signalled.
}
\section{\code{stdout} and \code{stderr}}{
By default, \code{abort()} and \code{inform()} print to standard output in
interactive sessions. This allows rlang to be in control of the
appearance of messages in IDEs like RStudio.
There are two situations where messages are streamed to \code{stderr}:
\itemize{
\item In non-interactive sessions, messages are streamed to standard
error so that R scripts can easily filter them out from normal
output by redirecting \code{stderr}.
\item If a sink is active (either on output or on messages) messages
are always streamd to \code{stderr}.
}
These exceptions ensure consistency of behaviour in interactive and
non-interactive sessions, and when sinks are active.
}
\examples{
# These examples are guarded to avoid throwing errors
if (FALSE) {
# Signal an error with a message just like stop():
abort("The error message.")
# Unhandled errors are saved automatically by `abort()` and can be
# retrieved with `last_error()`. The error prints with a simplified
# backtrace:
f <- function() try(g())
g <- function() evalq(h())
h <- function() abort("Tilt.")
last_error()
# Use `summary()` to print the full backtrace and the condition fields:
summary(last_error())
# Give a class to the error:
abort("The error message", "mypkg_bad_error")
# This allows callers to handle the error selectively
tryCatch(
mypkg_function(),
mypkg_bad_error = function(err) {
warn(conditionMessage(err)) # Demote the error to a warning
NA # Return an alternative value
}
)
# You can also specify metadata that will be stored in the condition:
abort("The error message.", "mypkg_bad_error", data = 1:10)
# This data can then be consulted by user handlers:
tryCatch(
mypkg_function(),
mypkg_bad_error = function(err) {
# Compute an alternative return value with the data:
recover_error(err$data)
}
)
# If you call low-level APIs it may be a good idea to create a
# chained error with the low-level error wrapped in a more
# user-friendly error. Use `try_fetch()` to fetch errors of a given
# class and rethrow them with the `parent` argument of `abort()`:
file <- "http://foo.bar/baz"
try(
try_fetch(
download(file),
error = function(err) {
msg <- sprintf("Can't download `\%s`", file)
abort(msg, parent = err)
})
)
}
}
rlang/man/expr_label.Rd 0000644 0001762 0000144 00000002371 14175213516 014544 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/expr.R
\name{expr_label}
\alias{expr_label}
\alias{expr_name}
\alias{expr_text}
\title{Turn an expression to a label}
\usage{
expr_label(expr)
expr_name(expr)
expr_text(expr, width = 60L, nlines = Inf)
}
\arguments{
\item{expr}{An expression to labellise.}
\item{width}{Width of each line.}
\item{nlines}{Maximum number of lines to extract.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#questioning}{\figure{lifecycle-questioning.svg}{options: alt='[Questioning]'}}}{\strong{[Questioning]}}
\code{expr_text()} turns the expression into a single string, which
might be multi-line. \code{expr_name()} is suitable for formatting
names. It works best with symbols and scalar types, but also
accepts calls. \code{expr_label()} formats the expression nicely for use
in messages.
}
\examples{
# To labellise a function argument, first capture it with
# substitute():
fn <- function(x) expr_label(substitute(x))
fn(x:y)
# Strings are encoded
expr_label("a\nb")
# Names and expressions are quoted with ``
expr_label(quote(x))
expr_label(quote(a + b + c))
# Long expressions are collapsed
expr_label(quote(foo({
1 + 2
print(x)
})))
}
\keyword{internal}
rlang/man/flatten.Rd 0000644 0001762 0000144 00000006014 14175213516 014062 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vec-squash.R
\name{flatten}
\alias{flatten}
\alias{flatten_lgl}
\alias{flatten_int}
\alias{flatten_dbl}
\alias{flatten_cpl}
\alias{flatten_chr}
\alias{flatten_raw}
\alias{squash}
\alias{squash_lgl}
\alias{squash_int}
\alias{squash_dbl}
\alias{squash_cpl}
\alias{squash_chr}
\alias{squash_raw}
\alias{flatten_if}
\alias{squash_if}
\title{Flatten or squash a list of lists into a simpler vector}
\usage{
flatten(x)
flatten_lgl(x)
flatten_int(x)
flatten_dbl(x)
flatten_cpl(x)
flatten_chr(x)
flatten_raw(x)
squash(x)
squash_lgl(x)
squash_int(x)
squash_dbl(x)
squash_cpl(x)
squash_chr(x)
squash_raw(x)
flatten_if(x, predicate = is_spliced)
squash_if(x, predicate = is_spliced)
}
\arguments{
\item{x}{A list to flatten or squash. The contents of the list can
be anything for unsuffixed functions \code{flatten()} and \code{squash()}
(as a list is returned), but the contents must match the type for
the other functions.}
\item{predicate}{A function of one argument returning whether it
should be spliced.}
}
\value{
\code{flatten()} returns a list, \code{flatten_lgl()} a logical
vector, \code{flatten_int()} an integer vector, \code{flatten_dbl()} a
double vector, and \code{flatten_chr()} a character vector. Similarly
for \code{squash()} and the typed variants (\code{squash_lgl()} etc).
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#questioning}{\figure{lifecycle-questioning.svg}{options: alt='[Questioning]'}}}{\strong{[Questioning]}}
\code{flatten()} removes one level hierarchy from a list, while
\code{squash()} removes all levels. These functions are similar to
\code{\link[=unlist]{unlist()}} but they are type-stable so you always know what the
type of the output is.
}
\section{Life cycle}{
These functions are in the questioning stage. They have slightly
different semantics than the flattening functions in purrr and we
are currently rethinking our approach to flattening with the new
typing facilities of the vctrs package.
}
\examples{
x <- replicate(2, sample(4), simplify = FALSE)
x
flatten(x)
flatten_int(x)
# With flatten(), only one level gets removed at a time:
deep <- list(1, list(2, list(3)))
flatten(deep)
flatten(flatten(deep))
# But squash() removes all levels:
squash(deep)
squash_dbl(deep)
# The typed flatten functions remove one level and coerce to an atomic
# vector at the same time:
flatten_dbl(list(1, list(2)))
# Only bare lists are flattened, but you can splice S3 lists
# explicitly:
foo <- set_attrs(list("bar"), class = "foo")
str(flatten(list(1, foo, list(100))))
str(flatten(list(1, splice(foo), list(100))))
# Instead of splicing manually, flatten_if() and squash_if() let
# you specify a predicate function:
is_foo <- function(x) inherits(x, "foo") || is_bare_list(x)
str(flatten_if(list(1, foo, list(100)), is_foo))
# squash_if() does the same with deep lists:
deep_foo <- list(1, list(foo, list(foo, 100)))
str(deep_foo)
str(squash(deep_foo))
str(squash_if(deep_foo, is_foo))
}
\keyword{internal}
rlang/man/string.Rd 0000644 0001762 0000144 00000002762 14175213516 013741 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utils-encoding.R
\name{string}
\alias{string}
\title{Create a string}
\usage{
string(x, encoding = NULL)
}
\arguments{
\item{x}{A character vector or a vector or list of string-like
objects.}
\item{encoding}{If non-null, set an encoding mark. This is only
declarative, no encoding conversion is performed.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
These base-type constructors allow more control over the creation
of strings in R. They take character vectors or string-like objects
(integerish or raw vectors), and optionally set the encoding. The
string version checks that the input contains a scalar string.
}
\examples{
# As everywhere in R, you can specify a string with Unicode
# escapes. The characters corresponding to Unicode codepoints will
# be encoded in UTF-8, and the string will be marked as UTF-8
# automatically:
cafe <- string("caf\uE9")
Encoding(cafe)
charToRaw(cafe)
# In addition, string() provides useful conversions to let
# programmers control how the string is represented in memory. For
# encodings other than UTF-8, you'll need to supply the bytes in
# hexadecimal form. If it is a latin1 encoding, you can mark the
# string explicitly:
cafe_latin1 <- string(c(0x63, 0x61, 0x66, 0xE9), "latin1")
Encoding(cafe_latin1)
charToRaw(cafe_latin1)
}
\keyword{internal}
rlang/man/new_quosures.Rd 0000644 0001762 0000144 00000001741 14127057575 015176 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/quo.R
\name{new_quosures}
\alias{new_quosures}
\alias{as_quosures}
\alias{is_quosures}
\title{Create a list of quosures}
\usage{
new_quosures(x)
as_quosures(x, env, named = FALSE)
is_quosures(x)
}
\arguments{
\item{x}{A list of quosures or objects to coerce to quosures.}
\item{env}{The default environment for the new quosures.}
\item{named}{Whether to name the list with \code{\link[=quos_auto_name]{quos_auto_name()}}.}
}
\description{
This small S3 class provides methods for \code{[} and \code{c()} and ensures
the following invariants:
\itemize{
\item The list only contains quosures.
\item It is always named, possibly with a vector of empty strings.
}
\code{new_quosures()} takes a list of quosures and adds the \code{quosures}
class and a vector of empty names if needed. \code{as_quosures()} calls
\code{\link[=as_quosure]{as_quosure()}} on all elements before creating the \code{quosures}
object.
}
rlang/man/search_envs.Rd 0000644 0001762 0000144 00000006127 14127057575 014742 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-special.R
\name{search_envs}
\alias{search_envs}
\alias{search_env}
\alias{pkg_env}
\alias{pkg_env_name}
\alias{is_attached}
\alias{base_env}
\alias{global_env}
\title{Search path environments}
\usage{
search_envs()
search_env(name)
pkg_env(pkg)
pkg_env_name(pkg)
is_attached(x)
base_env()
global_env()
}
\arguments{
\item{name}{The name of an environment attached to the search
path. Call \code{\link[base:search]{base::search()}} to get the names of environments
currently attached to the search path. Note that the search name
of a package environment is prefixed with \code{"package:"}.}
\item{pkg}{The name of a package.}
\item{x}{An environment or a search name.}
}
\description{
The search path is a chain of environments containing exported
functions of attached packages.
The API includes:
\itemize{
\item \code{\link[base:search]{base::search()}} to get the names of environments attached to the
search path.
\item \code{search_envs()} returns the environments on the search path as a
list.
\item \code{pkg_env_name()} takes a bare package name and prefixes it with
\code{"package:"}. Attached package environments have search names of
the form \code{package:name}.
\item \code{pkg_env()} takes a bare package name and returns the scoped
environment of packages if they are attached to the search path,
and throws an error otherwise. It is a shortcut for
\code{search_env(pkg_env_name("pkgname"))}.
\item \code{global_env()} and \code{base_env()} (simple aliases for \code{\link[=globalenv]{globalenv()}}
and \code{\link[=baseenv]{baseenv()}}). These are respectively the first and last
environments of the search path.
\item \code{is_attached()} returns \code{TRUE} when its argument (a search name
or a package environment) is attached to the search path.
}
}
\section{The search path}{
This chain of environments determines what objects are visible from
the global workspace. It contains the following elements:
\itemize{
\item The chain always starts with \code{global_env()} and finishes with
\code{base_env()} which inherits from the terminal environment
\code{empty_env()}.
\item Each \code{\link[base:library]{base::library()}} call attaches a new package environment to
the search path. Attached packages are associated with a \link[=env_name]{search name}.
\item In addition, any list, data frame, or environment can be attached
to the search path with \code{\link[base:attach]{base::attach()}}.
}
}
\examples{
# List the search names of environments attached to the search path:
search()
# Get the corresponding environments:
search_envs()
# The global environment and the base package are always first and
# last in the chain, respectively:
envs <- search_envs()
envs[[1]]
envs[[length(envs)]]
# These two environments have their own shortcuts:
global_env()
base_env()
# Packages appear in the search path with a special name. Use
# pkg_env_name() to create that name:
pkg_env_name("rlang")
search_env(pkg_env_name("rlang"))
# Alternatively, get the scoped environment of a package with
# pkg_env():
pkg_env("utils")
}
\keyword{internal}
rlang/man/splice-operator.Rd 0000644 0001762 0000144 00000016416 14176517136 015552 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nse-inject.R
\name{splice-operator}
\alias{splice-operator}
\alias{!!!}
\title{Splice operator \verb{!!!}}
\description{
The splice operator \verb{!!!} implemented in \link[=dyn-dots]{dynamic dots}
injects a list of arguments into a function call. It belongs to the
family of \link[=topic-inject]{injection} operators and provides the same
functionality as \code{\link[=do.call]{do.call()}}.
The two main cases for splice injection are:
\itemize{
\item Turning a list of inputs into distinct arguments. This is
especially useful with functions that take data in \code{...}, such as
\code{\link[base:cbind]{base::rbind()}}.\if{html}{\out{
}}
\item Injecting \link[=topic-defuse]{defused expressions} like
\link[=sym]{symbolised} column names.
For tidyverse APIs, this second case is no longer as useful
since dplyr 1.0 and the \code{across()} operator.
}
}
\section{Where does \verb{!!!} work?}{
\verb{!!!} does not work everywhere, you can only use it within certain
special functions:
\itemize{
\item Functions taking \link[=dyn-dots]{dynamic dots} like \code{\link[=list2]{list2()}}.
\item Functions taking \link[=topic-defuse]{defused} and
\link[=topic-data-mask]{data-masked} arguments, which are dynamic by
default.
\item Inside \code{\link[=inject]{inject()}}.
}
Most tidyverse functions support \verb{!!!} out of the box. With base
functions you need to use \code{\link[=inject]{inject()}} to enable \verb{!!!}.
Using the operator out of context may lead to incorrect results,
see \ifelse{html}{\link[=topic-inject-out-of-context]{What happens if I use injection operators out of context?}}{\link[=topic-inject-out-of-context]{What happens if I use injection operators out of context?}}.
}
\section{Splicing a list of arguments}{
Take a function like \code{\link[base:cbind]{base::rbind()}} that takes data in \code{...}. This
sort of functions takes a variable number of arguments.\if{html}{\out{
}}
Passing individual arguments is only possible for a fixed amount of
arguments. When the arguments are in a list whose length is
variable (and potentially very large), we need a programmatic
approach like the splicing syntax \verb{!!!}:\if{html}{\out{
}}
Because \code{rbind()} is a base function we used \code{\link[=inject]{inject()}} to
explicitly enable \verb{!!!}. However, many functions implement \link[=list2]{dynamic dots} with \verb{!!!} implicitly enabled out of the box.\if{html}{\out{
}}\preformatted{tidyr::expand_grid(x = 1:2, y = c("a", "b"))
#> # A tibble: 4 × 2
#> x y
#>
#> 1 1 a
#> 2 1 b
#> 3 2 a
#> 4 2 b
xs <- list(x = 1:2, y = c("a", "b"))
tidyr::expand_grid(!!!xs)
#> # A tibble: 4 × 2
#> x y
#>
#> 1 1 a
#> 2 1 b
#> 3 2 a
#> 4 2 b
}\if{html}{\out{
}}
Note how the expanded grid has the right column names. That's
because we spliced a \emph{named} list. Splicing causes each name of the
list to become an argument name.\if{html}{\out{
}}\preformatted{tidyr::expand_grid(!!!set_names(xs, toupper))
#> # A tibble: 4 × 2
#> X Y
#>
#> 1 1 a
#> 2 1 b
#> 3 2 a
#> 4 2 b
}\if{html}{\out{
}}
}
\section{Splicing a list of expressions}{
Another usage for \verb{!!!} is to inject \link[=topic-defuse]{defused expressions} into \link[=topic-data-mask]{data-masked}
dots. However this usage is no longer a common pattern for
programming with tidyverse functions and we recommend using other
patterns if possible.
First, instead of using the \link[=topic-data-mask-programming]{defuse-and-inject pattern} with \code{...}, you can simply pass
them on as you normally would. These two expressions are completely
equivalent:\if{html}{\out{
}}
Second, more complex applications such as \link[=topic-metaprogramming]{transformation patterns} can be solved with the \code{across()}
operation introduced in dplyr 1.0. Say you want to take the
\code{mean()} of all expressions in \code{...}. Before \code{across()}, you had to
defuse the \code{...} expressions, wrap them in a call to \code{mean()}, and
inject them in \code{summarise()}.\if{html}{\out{
}}\preformatted{my_mean <- function(.data, ...) \{
# Defuse dots and auto-name them
exprs <- enquos(..., .named = TRUE)
# Wrap the expressions in a call to `mean()`
exprs <- purrr::map(exprs, ~ call("mean", .x, na.rm = TRUE))
# Inject them
.data \%>\% dplyr::summarise(!!!exprs)
\}
}\if{html}{\out{
}}
It is much easier to use \code{across()} instead:\if{html}{\out{
}}
While the result is the same, what is going on under the hood is
completely different. \code{\link[=list2]{list2()}} is a dots collector that
special-cases \verb{!!!} arguments. On the other hand, \code{\link[=inject]{inject()}}
operates on the language and creates a function call containing as
many arguments as there are elements in the spliced list. If you
supply a list of size 1e6, \code{inject()} is creating one million
arguments before evaluation. This can be much slower.\if{html}{\out{
}}\preformatted{xs <- rep(list(1), 1e6)
system.time(
n_args(!!!xs)
)
#> user system elapsed
#> 0.009 0.000 0.009
system.time(
inject(n_args(!!!xs))
)
#> user system elapsed
#> 0.445 0.012 0.457
}\if{html}{\out{
}}
The same issue occurs when functions taking dynamic dots are called
inside a data-masking function like \code{dplyr::mutate()}. The
mechanism that enables \verb{!!!} injection in these arguments is the
same as in \code{inject()}.
}
\seealso{
\itemize{
\item \ifelse{html}{\link[=topic-inject]{Injecting with !!, !!!, and glue syntax}}{\link[=topic-inject]{Injecting with !!, !!!, and glue syntax}}
\item \code{\link[=inject]{inject()}}
\item \code{\link[=exec]{exec()}}
}
}
rlang/man/env_parent.Rd 0000644 0001762 0000144 00000004150 14137447476 014601 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env.R
\name{env_parent}
\alias{env_parent}
\alias{env_tail}
\alias{env_parents}
\title{Get parent environments}
\usage{
env_parent(env = caller_env(), n = 1)
env_tail(env = caller_env(), last = global_env())
env_parents(env = caller_env(), last = global_env())
}
\arguments{
\item{env}{An environment.}
\item{n}{The number of generations to go up.}
\item{last}{The environment at which to stop. Defaults to the
global environment. The empty environment is always a stopping
condition so it is safe to leave the default even when taking the
tail or the parents of an environment on the search path.
\code{env_tail()} returns the environment which has \code{last} as parent
and \code{env_parents()} returns the list of environments up to \code{last}.}
}
\value{
An environment for \code{env_parent()} and \code{env_tail()}, a list
of environments for \code{env_parents()}.
}
\description{
\itemize{
\item \code{env_parent()} returns the parent environment of \code{env} if called
with \code{n = 1}, the grandparent with \code{n = 2}, etc.
\item \code{env_tail()} searches through the parents and returns the one
which has \code{\link[=empty_env]{empty_env()}} as parent.
\item \code{env_parents()} returns the list of all parents, including the
empty environment. This list is named using \code{\link[=env_name]{env_name()}}.
}
See the section on \emph{inheritance} in \code{\link[=env]{env()}}'s documentation.
}
\examples{
# Get the parent environment with env_parent():
env_parent(global_env())
# Or the tail environment with env_tail():
env_tail(global_env())
# By default, env_parent() returns the parent environment of the
# current evaluation frame. If called at top-level (the global
# frame), the following two expressions are equivalent:
env_parent()
env_parent(base_env())
# This default is more handy when called within a function. In this
# case, the enclosure environment of the function is returned
# (since it is the parent of the evaluation frame):
enclos_env <- env()
fn <- set_env(function() env_parent(), enclos_env)
identical(enclos_env, fn())
}
rlang/man/on_load.Rd 0000644 0001762 0000144 00000006322 14175213516 014042 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/aaa.R
\name{on_load}
\alias{on_load}
\alias{run_on_load}
\alias{on_package_load}
\title{Run expressions on load}
\usage{
on_load(expr, env = parent.frame(), ns = topenv(env))
run_on_load(ns = topenv(parent.frame()))
on_package_load(pkg, expr, env = parent.frame())
}
\arguments{
\item{expr}{An expression to run on load.}
\item{env}{The environment in which to evaluate \code{expr}. Defaults to
the current environment, which is your package namespace if you
run \code{on_load()} at top level.}
\item{ns}{The namespace in which to hook \code{expr}.}
\item{pkg}{Package to hook expression into.}
}
\description{
\itemize{
\item \code{on_load()} registers expressions to be run on the user's machine
each time the package is loaded in memory. This is by contrast to
normal R package code which is run once at build time on the
packager's machine (e.g. CRAN).
\code{on_load()} expressions require \code{run_on_load()} to be called
inside \code{\link[=.onLoad]{.onLoad()}}.
\item \code{on_package_load()} registers expressions to be run each time
another package is loaded.
}
\code{on_load()} is for your own package and runs expressions when the
namespace is not \emph{sealed} yet. This means you can modify existing
binding or create new ones. This is not the case with
\code{on_package_load()} which runs expressions after a foreign package
has finished loading, at which point its namespace is sealed.
}
\section{When should I run expressions on load?}{
There are two main use cases for running expressions on load:
\enumerate{
\item When a side effect, such as registering a method with
\code{s3_register()}, must occur in the user session rather than the
package builder session.
\item To avoid hard-coding objects from other packages in your
namespace. If you assign \code{foo::bar} or the result of
\code{foo::baz()} in your package, they become constants. Any
upstream changes in the \code{foo} package will not be reflected in
the objects you've assigned in your namespace. This often breaks
assumptions made by the authors of \code{foo} and causes all sorts of
issues.
Recreating the foreign objects each time your package is loaded
makes sure that any such changes will be taken into account. In
technical terms, running an expression on load introduces
\emph{indirection}.
}
}
\section{Comparison with \code{.onLoad()}}{
\code{on_load()} has the advantage that hooked expressions can appear in
any file, in context. This is unlike \code{.onLoad()} which gathers
disparate expressions in a single block.
\code{on_load()} is implemented via \code{.onLoad()} and requires
\code{run_on_load()} to be called from that hook.
}
\examples{
quote({ # Not run
# First add `run_on_load()` to your `.onLoad()` hook,
# then use `on_load()` anywhere in your package
.onLoad <- function(lib, pkg) {
run_on_load()
}
# Register a method on load
on_load(s3_register("foo::bar", "my_class"))
# Assign an object on load
var <- NULL
on_load(
var <- foo()
)
# To use `on_package_load()` at top level, wrap it in `on_load()`
on_load(on_package_load("foo", message("foo is loaded")))
# In functions it can be called directly
f <- function() on_package_load("foo", message("foo is loaded"))
})
}
rlang/man/env_cache.Rd 0000644 0001762 0000144 00000001773 14175213516 014347 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-binding.R
\name{env_cache}
\alias{env_cache}
\title{Cache a value in an environment}
\usage{
env_cache(env, nm, default)
}
\arguments{
\item{env}{An environment.}
\item{nm}{Names of bindings. \code{nm} must be a single string.}
\item{default}{The default value to store in \code{env} if \code{nm} does not
exist yet.}
}
\value{
Either the value of \code{nm} or \code{default} if it did not exist
yet.
}
\description{
\code{env_cache()} is a wrapper around \code{\link[=env_get]{env_get()}} and \code{\link[=env_poke]{env_poke()}}
designed to retrieve a cached value from \code{env}.
\itemize{
\item If the \code{nm} binding exists, it returns its value.
\item Otherwise, it stores the default value in \code{env} and returns that.
}
}
\examples{
e <- env(a = "foo")
# Returns existing binding
env_cache(e, "a", "default")
# Creates a `b` binding and returns its default value
env_cache(e, "b", "default")
# Now `b` is defined
e$b
}
rlang/man/rlib_trace_spec.Rd 0000644 0001762 0000144 00000003550 14175213516 015547 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/trace.R
\name{rlib_trace_spec}
\alias{rlib_trace_spec}
\title{Backtrace specification}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
}
\section{Structure}{
An r-lib backtrace is a data frame that contains the following
columns:
\itemize{
\item \code{call}: List of calls. These may carry \code{srcref} objects.
\item \code{visible}: Logical vector. If \code{FALSE}, the corresponding call
will be hidden from simplified backtraces.
\item \code{parent}: Integer vector of parent references (see
\code{\link[=sys.parents]{sys.parents()}}) as row numbers. 0 is global.
\item \code{namespace}: Character vector of namespaces. \code{NA} for global or
no namespace
\item \code{scope}: Character vector of strings taking values \code{"::"},
\code{":::"}, \code{"global"}, or \code{"local"}.
}
A backtrace data frame may contain extra columns. If you add
additional columns, make sure to prefix their names with the name
of your package or organisation to avoid potential conflicts with
future extensions of this spec, e.g. \code{"mypkg_column"}.
}
\section{Operations}{
\itemize{
\item \strong{Length}. The length of the backtrace is the number of rows of
the underlying data.
\item \strong{Concatenation}. Performed by row-binding two backtraces. The
\code{parent} column of the RHS is shifted by \code{nrow(LHS)} so that the
last call of the LHS takes place of the global frame of the RHS.
\item \strong{Subsetting}. Performed by slicing the backtrace. After the
data frame is sliced, the \code{parent} column is adjusted to the new
row indices. Any \code{parent} value that no longer exists in the
sliced backtrace is set to 0 (the global frame).
}
}
\keyword{internal}
rlang/man/rlang-package.Rd 0000644 0001762 0000144 00000002071 14175213516 015120 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rlang.R
\docType{package}
\name{rlang-package}
\alias{rlang}
\alias{rlang-package}
\title{rlang: Functions for Base Types and Core R and 'Tidyverse' Features}
\description{
\if{html}{\figure{logo.png}{options: align='right' alt='logo' width='120'}}
A toolbox for working with base types, core R features like the condition system, and core 'Tidyverse' features like tidy evaluation.
}
\seealso{
Useful links:
\itemize{
\item \url{https://rlang.r-lib.org}
\item \url{https://github.com/r-lib/rlang}
\item Report bugs at \url{https://github.com/r-lib/rlang/issues}
}
}
\author{
\strong{Maintainer}: Lionel Henry \email{lionel@rstudio.com}
Authors:
\itemize{
\item Hadley Wickham \email{hadley@rstudio.com}
}
Other contributors:
\itemize{
\item mikefc \email{mikefc@coolbutuseless.com} (Hash implementation based on Mike's xxhashlite) [copyright holder]
\item Yann Collet (Author of the embedded xxHash library) [copyright holder]
\item RStudio [copyright holder]
}
}
\keyword{internal}
rlang/man/ns_env.Rd 0000644 0001762 0000144 00000002017 14175213516 013714 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-special.R
\name{ns_env}
\alias{ns_env}
\alias{ns_imports_env}
\alias{ns_env_name}
\title{Get the namespace of a package}
\usage{
ns_env(x = caller_env())
ns_imports_env(x = caller_env())
ns_env_name(x = caller_env())
}
\arguments{
\item{x}{\itemize{
\item For \code{ns_env()}, the name of a package or an environment as a
string.
\itemize{
\item An environment (the current environment by default).
\item A function.
}
In the latter two cases, the environment ancestry is searched for
a namespace with \code{\link[base:ns-topenv]{base::topenv()}}. If the environment doesn't
inherit from a namespace, this is an error.
}}
\item{env}{A namespace environment.}
}
\description{
Namespaces are the environment where all the functions of a package
live. The parent environments of namespaces are the \code{imports}
environments, which contain all the functions imported from other
packages.
}
\seealso{
\code{\link[=pkg_env]{pkg_env()}}
}
\keyword{internal}
rlang/man/is_formula.Rd 0000644 0001762 0000144 00000005174 14175213516 014573 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/formula.R
\name{is_formula}
\alias{is_formula}
\alias{is_bare_formula}
\title{Is object a formula?}
\usage{
is_formula(x, scoped = NULL, lhs = NULL)
is_bare_formula(x, scoped = TRUE, lhs = NULL)
}
\arguments{
\item{x}{An object to test.}
\item{scoped}{A boolean indicating whether the quosure is scoped,
that is, has a valid environment attribute and inherits from
\code{"formula"}. If \code{NULL}, the scope is not inspected.}
\item{lhs}{A boolean indicating whether the formula has a left-hand
side. If \code{NULL}, the LHS is not inspected and \code{is_formula()}
returns \code{TRUE} for both one- and two-sided formulas.}
}
\description{
\code{is_formula()} tests whether \code{x} is a call to \code{~}. \code{is_bare_formula()}
tests in addition that \code{x} does not inherit from anything else than
\code{"formula"}.
\strong{Note}: When we first implemented \code{is_formula()}, we thought it
best to treat unevaluated formulas as formulas by default (see
section below). Now we think this default introduces too many edge
cases in normal code. We recommend always supplying \code{scoped = TRUE}. Unevaluated formulas can be handled via a \code{is_call(x, "~")}
branch.
}
\section{Dealing with unevaluated formulas}{
At parse time, a formula is a simple call to \code{~} and it does not
have a class or an environment. Once evaluated, the \code{~} call
becomes a properly structured formula. Unevaluated formulas arise
by quotation, e.g. \code{~~foo}, \code{quote(~foo)}, or \code{substitute(arg)}
with \code{arg} being supplied a formula. Use the \code{scoped} argument to
check whether the formula carries an environment.
}
\examples{
is_formula(~10)
is_formula(10)
# If you don't supply `lhs`, both one-sided and two-sided formulas
# will return `TRUE`
is_formula(disp ~ am)
is_formula(~am)
# You can also specify whether you expect a LHS:
is_formula(disp ~ am, lhs = TRUE)
is_formula(disp ~ am, lhs = FALSE)
is_formula(~am, lhs = TRUE)
is_formula(~am, lhs = FALSE)
# Handling of unevaluated formulas is a bit tricky. These formulas
# are special because they don't inherit from `"formula"` and they
# don't carry an environment (they are not scoped):
f <- quote(~foo)
f_env(f)
# By default unevaluated formulas are treated as formulas
is_formula(f)
# Supply `scoped = TRUE` to ensure you have an evaluated formula
is_formula(f, scoped = TRUE)
# By default unevaluated formulas not treated as bare formulas
is_bare_formula(f)
# If you supply `scoped = TRUE`, they will be considered bare
# formulas even though they don't inherit from `"formula"`
is_bare_formula(f, scoped = TRUE)
}
rlang/man/UQ.Rd 0000644 0001762 0000144 00000001037 14175213516 012752 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{UQ}
\alias{UQ}
\alias{UQS}
\title{Deprecated \code{UQ()} and \code{UQS()} operators}
\usage{
UQ(x)
UQS(x)
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
These operators are deprecated in favour of
\code{\link[=injection-operator]{!!}} and \code{\link[=splice-operator]{!!!}}.
}
\keyword{internal}
rlang/man/call_args.Rd 0000644 0001762 0000144 00000001447 14175213516 014361 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/call.R
\name{call_args}
\alias{call_args}
\alias{call_args_names}
\title{Extract arguments from a call}
\usage{
call_args(call)
call_args_names(call)
}
\arguments{
\item{call}{A defused call.}
}
\value{
A named list of arguments.
}
\description{
Extract arguments from a call
}
\examples{
call <- quote(f(a, b))
# Subsetting a call returns the arguments converted to a language
# object:
call[-1]
# On the other hand, call_args() returns a regular list that is
# often easier to work with:
str(call_args(call))
# When the arguments are unnamed, a vector of empty strings is
# supplied (rather than NULL):
call_args_names(call)
}
\seealso{
\code{\link[=fn_fmls]{fn_fmls()}} and \code{\link[=fn_fmls_names]{fn_fmls_names()}}
}
rlang/man/as_label.Rd 0000644 0001762 0000144 00000003652 14175213516 014174 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/deparse.R
\name{as_label}
\alias{as_label}
\title{Create a default name for an R object}
\usage{
as_label(x)
}
\arguments{
\item{x}{An object.}
}
\description{
\code{as_label()} transforms R objects into a short, human-readable
description. You can use labels to:
\itemize{
\item Display an object in a concise way, for example to labellise axes
in a graphical plot.
\item Give default names to columns in a data frame. In this case,
labelling is the first step before name repair.
}
See also \code{\link[=as_name]{as_name()}} for transforming symbols back to a
string. Unlike \code{as_label()}, \code{as_name()} is a well defined
operation that guarantees the roundtrip symbol -> string ->
symbol.
In general, if you don't know for sure what kind of object you're
dealing with (a call, a symbol, an unquoted constant), use
\code{as_label()} and make no assumption about the resulting string. If
you know you have a symbol and need the name of the object it
refers to, use \code{\link[=as_name]{as_name()}}. For instance, use \code{as_label()} with
objects captured with \code{enquo()} and \code{as_name()} with symbols
captured with \code{ensym()}.
}
\section{Transformation to string}{
\itemize{
\item Quosures are \link[=quo_squash]{squashed} before being labelled.
\item Symbols are transformed to string with \code{as_string()}.
\item Calls are abbreviated.
\item Numbers are represented as such.
\item Other constants are represented by their type, such as \verb{}
or \verb{}.
}
}
\examples{
# as_label() is useful with quoted expressions:
as_label(expr(foo(bar)))
as_label(expr(foobar))
# It works with any R object. This is also useful for quoted
# arguments because the user might unquote constant objects:
as_label(1:3)
as_label(base::list)
}
\seealso{
\code{\link[=as_name]{as_name()}} for transforming symbols back to a string
deterministically.
}
rlang/man/last_warnings.Rd 0000644 0001762 0000144 00000005071 14175213516 015302 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-last.R
\name{last_warnings}
\alias{last_warnings}
\alias{last_messages}
\title{Display last warnings}
\usage{
last_warnings(n = NULL)
last_messages(n = NULL)
}
\arguments{
\item{n}{How many warnings or messages to display. Defaults to all.}
}
\description{
\code{last_warnings()} and \code{last_messages()} return a list of all
warnings and messages that occurred during the last R command.
\code{\link[=global_entrace]{global_entrace()}} must be active in order to log the messages and
warnings.
By default the warnings and messages are printed with a simplified
backtrace, like \code{\link[=last_error]{last_error()}}. Use \code{summary()} to print the
conditions with a full backtrace.
}
\section{Examples}{
Enable backtrace capture with \code{global_entrace()}:\if{html}{\out{
}}\preformatted{global_entrace()
}\if{html}{\out{
}}
Signal some warnings in nested functions. The warnings inform about
which function emitted a warning but they don't provide information
about the call stack:\if{html}{\out{
}}\preformatted{f <- function() \{ warning("foo"); g() \}
g <- function() \{ warning("bar", immediate. = TRUE); h() \}
h <- function() warning("baz")
f()
#> Warning in g() : bar
#> Warning messages:
#> 1: In f() : foo
#> 2: In h() : baz
}\if{html}{\out{
}}
Call \code{last_warnings()} to see backtraces for each of these warnings:\if{html}{\out{
}}\preformatted{last_warnings()
#> [[1]]
#>
#> Warning in `f()`: foo
#> Backtrace:
#> 1. global f()
#>
#> [[2]]
#>
#> Warning in `g()`: bar
#> Backtrace:
#> 1. global f()
#> 2. global g()
#>
#> [[3]]
#>
#> Warning in `h()`: baz
#> Backtrace:
#> 1. global f()
#> 2. global g()
#> 3. global h()
}\if{html}{\out{
}}
To get a full backtrace, use \code{\link[=summary]{summary()}}. In this case the full
backtraces do not include more information:\if{html}{\out{
}}\preformatted{summary(last_warnings())
#> [[1]]
#>
#> Warning in `f()`:
#> foo
#> Backtrace:
#> x
#> 1. \\-global f()
#>
#> [[2]]
#>
#> Warning in `g()`:
#> bar
#> Backtrace:
#> x
#> 1. \\-global f()
#> 2. \\-global g()
#>
#> [[3]]
#>
#> Warning in `h()`:
#> baz
#> Backtrace:
#> x
#> 1. \\-global f()
#> 2. \\-global g()
#> 3. \\-global h()
}\if{html}{\out{
}}
}
\seealso{
\code{\link[=last_error]{last_error()}}
}
rlang/man/is_lang.Rd 0000644 0001762 0000144 00000002613 14175213516 014042 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{is_lang}
\alias{is_lang}
\title{Is object a call?}
\usage{
is_lang(x, name = NULL, n = NULL, ns = NULL)
}
\arguments{
\item{x}{An object to test. Formulas and quosures are treated
literally.}
\item{name}{An optional name that the call should match. It is
passed to \code{\link[=sym]{sym()}} before matching. This argument is vectorised
and you can supply a vector of names to match. In this case,
\code{is_call()} returns \code{TRUE} if at least one name matches.}
\item{n}{An optional number of arguments that the call should
match.}
\item{ns}{The namespace of the call. If \code{NULL}, the namespace
doesn't participate in the pattern-matching. If an empty string
\code{""} and \code{x} is a namespaced call, \code{is_call()} returns
\code{FALSE}. If any other string, \code{is_call()} checks that \code{x} is
namespaced within \code{ns}.
Can be a character vector of namespaces, in which case the call
has to match at least one of them, otherwise \code{is_call()} returns
\code{FALSE}.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
These functions are deprecated, please use \code{\link[=is_call]{is_call()}} and its \code{n}
argument instead.
}
\keyword{internal}
rlang/man/vector-old-ctors.Rd 0000644 0001762 0000144 00000001230 14175213516 015626 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{vector-old-ctors}
\alias{vector-old-ctors}
\alias{lgl_along}
\alias{int_along}
\title{Retired vector construction by length}
\usage{
lgl_along(.x)
int_along(.x)
}
\arguments{
\item{.x}{A vector.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
These functions were deprecated and renamed with \code{new_} prefix in
rlang 0.2.0. This is for consistency with other non-variadic object
constructors.
}
\keyword{internal}
rlang/man/topic-double-evaluation.Rd 0000644 0001762 0000144 00000010033 14175213516 017154 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/topic-nse.R
\name{topic-double-evaluation}
\alias{topic-double-evaluation}
\title{The double evaluation problem}
\description{
One inherent risk to metaprogramming is to evaluate multiple times a piece of code that appears to be evaluated only once. Take this data-masking function which takes a single input and produces two summaries:\if{html}{\out{
}}\preformatted{summarise_stats <- function(data, var) \{
data \%>\%
dplyr::summarise(
mean = mean(\{\{ var \}\}),
sd = sd(\{\{ var \}\})
)
\}
summarise_stats(mtcars, cyl)
#> # A tibble: 1 x 2
#> mean sd
#>
#> 1 6.19 1.79
}\if{html}{\out{
}}
This function is perfectly fine if the user supplies simple column names. However, data-masked arguments may also include \emph{computations}.\if{html}{\out{
}}\preformatted{summarise_stats(mtcars, cyl * 100)
#> # A tibble: 1 x 2
#> mean sd
#>
#> 1 619. 179.
}\if{html}{\out{
}}
Computations may be slow and may produce side effects. For these
reasons, they should only be performed as many times as they appear in the code (unless explicitly documented, e.g. once per group with grouped data frames). Let's try again with a more complex computation:\if{html}{\out{
}}\preformatted{times100 <- function(x) \{
message("Takes a long time...")
Sys.sleep(0.1)
message("And causes side effects such as messages!")
x * 100
\}
summarise_stats(mtcars, times100(cyl))
#> Takes a long time...
#> And causes side effects such as messages!
#> Takes a long time...
#> And causes side effects such as messages!
#> # A tibble: 1 x 2
#> mean sd
#>
#> 1 619. 179.
}\if{html}{\out{
}}
Because of the side effects and the long running time, it is clear that \code{summarise_stats()} evaluates its input twice. This is because we've injected a defused expression in two different places. The data-masked expression created down the line looks like this (with caret signs representing \link[=topic-quosure]{quosure} boundaries):\if{html}{\out{
}}\preformatted{dplyr::summarise(
mean = ^mean(^times100(cyl)),
sd = ^sd(^times100(cyl))
)
}\if{html}{\out{
}}
The \code{times100(cyl)} expression is evaluated twice, even though it only appears once in the code. We have a double evaluation bug.
One simple way to fix it is to assign the defused input to a constant. You can then refer to that constant in the remaining of the code.\if{html}{\out{
}}\preformatted{summarise_stats <- function(data, var) \{
data \%>\%
dplyr::transmute(
var = \{\{ var \}\},
) \%>\%
dplyr::summarise(
mean = mean(var),
sd = sd(var)
)
\}
}\if{html}{\out{
}}
The defused input is now evaluated only once because it is injected only once:\if{html}{\out{
}}\preformatted{summarise_stats(mtcars, times100(cyl))
#> Takes a long time...
#> And causes side effects such as messages!
#> # A tibble: 1 x 2
#> mean sd
#>
#> 1 619. 179.
}\if{html}{\out{
}}
}
\section{What about glue strings?}{
\verb{\{\{} \link[=glue-operators]{embracing in glue strings} doesn't suffer from the double evaluation problem:\if{html}{\out{
}}\preformatted{summarise_stats <- function(data, var) \{
data \%>\%
dplyr::transmute(
var = \{\{ var \}\},
) \%>\%
dplyr::summarise(
"mean_\{\{ var \}\}" := mean(var),
"sd_\{\{ var \}\}" := sd(var)
)
\}
summarise_stats(mtcars, times100(cyl))
#> Takes a long time...
#> And causes side effects such as messages!
#> # A tibble: 1 x 2
#> `mean_times100(cyl)` `sd_times100(cyl)`
#>
#> 1 619. 179.
}\if{html}{\out{
}}
Since a glue string doesn't need the result of an expression, only the original code converted (deparsed) to a string, it doesn't evaluate injected expressions.
}
\keyword{internal}
rlang/man/seq2.Rd 0000644 0001762 0000144 00000001470 14127057575 013310 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vec.R
\name{seq2}
\alias{seq2}
\alias{seq2_along}
\title{Increasing sequence of integers in an interval}
\usage{
seq2(from, to)
seq2_along(from, x)
}
\arguments{
\item{from}{The starting point of the sequence.}
\item{to}{The end point.}
\item{x}{A vector whose length is the end point.}
}
\value{
An integer vector containing a strictly increasing
sequence.
}
\description{
These helpers take two endpoints and return the sequence of all
integers within that interval. For \code{seq2_along()}, the upper
endpoint is taken from the length of a vector. Unlike
\code{base::seq()}, they return an empty vector if the starting point is
a larger integer than the end point.
}
\examples{
seq2(2, 10)
seq2(10, 2)
seq(10, 2)
seq2_along(10, letters)
}
rlang/man/switch_type.Rd 0000644 0001762 0000144 00000004605 14175213516 014773 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{switch_type}
\alias{switch_type}
\alias{coerce_type}
\alias{switch_class}
\alias{coerce_class}
\title{Dispatch on base types}
\usage{
switch_type(.x, ...)
coerce_type(.x, .to, ...)
switch_class(.x, ...)
coerce_class(.x, .to, ...)
}
\arguments{
\item{.x}{An object from which to dispatch.}
\item{...}{Named clauses. The names should be types as returned by
\code{\link[=type_of]{type_of()}}.}
\item{.to}{This is useful when you switchpatch within a coercing
function. If supplied, this should be a string indicating the
target type. A catch-all clause is then added to signal an error
stating the conversion failure. This type is prettified unless
\code{.to} inherits from the S3 class \code{"AsIs"} (see \code{\link[base:AsIs]{base::I()}}).}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#soft-deprecated}{\figure{lifecycle-soft-deprecated.svg}{options: alt='[Soft-deprecated]'}}}{\strong{[Soft-deprecated]}}
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
\code{switch_type()} is equivalent to
\code{\link[base]{switch}(\link{type_of}(x, ...))}, while
\code{switch_class()} switchpatches based on \code{class(x)}. The \code{coerce_}
versions are intended for type conversion and provide a standard
error message when conversion fails.
}
\examples{
switch_type(3L,
double = "foo",
integer = "bar",
"default"
)
# Use the coerce_ version to get standardised error handling when no
# type matches:
to_chr <- function(x) {
coerce_type(x, "a chr",
integer = as.character(x),
double = as.character(x)
)
}
to_chr(3L)
# Strings have their own type:
switch_type("str",
character = "foo",
string = "bar",
"default"
)
# Use a fallthrough clause if you need to dispatch on all character
# vectors, including strings:
switch_type("str",
string = ,
character = "foo",
"default"
)
# special and builtin functions are treated as primitive, since
# there is usually no reason to treat them differently:
switch_type(base::list,
primitive = "foo",
"default"
)
switch_type(base::`$`,
primitive = "foo",
"default"
)
# closures are not primitives:
switch_type(rlang::switch_type,
primitive = "foo",
"default"
)
}
\keyword{internal}
rlang/man/dev-notes-dots.Rd 0000644 0001762 0000144 00000002272 14175213516 015302 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dots.R
\name{dev-notes-dots}
\alias{dev-notes-dots}
\title{Development notes - \code{dots.R}}
\description{
Development notes - \code{dots.R}
}
\section{\code{.__error_call__.} flag in dots collectors}{
Dots collectors like \code{\link[=dots_list]{dots_list()}} are a little tricky because they
may error out in different situations. Do we want to forward the
context, i.e. set the call flag to the calling environment?
Collectors throw errors in these cases:
\enumerate{
\item While checking their own parameters, in which case the relevant
context is the collector itself and we don't forward.
\item While collecting the dots, during evaluation of the supplied
arguments. In this case forwarding or not is irrelevant because
expressions in \code{...} are evaluated in their own environment
which is not connected to the collector's context.
\item While collecting the dots, during argument constraints checks
such as determined by the \code{.homonyms} argument. In this case we
want to forward the context because the caller of the dots
collector is the one who determines the constraints for its
users.
}
}
\keyword{internal}
rlang/man/topic-data-mask.Rd 0000644 0001762 0000144 00000021714 14175213516 015407 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/topic-nse.R
\name{topic-data-mask}
\alias{topic-data-mask}
\title{What is data-masking and why do I need \verb{\{\{}?}
\description{
Data-masking is a distinctive feature of R whereby programming is performed directly on a data set, with columns defined as normal objects.\if{html}{\out{
}}\preformatted{# Unmasked programming
mean(mtcars$cyl + mtcars$am)
#> [1] 6.59375
# Referring to columns is an error - Where is the data?
mean(cyl + am)
#> Error in mean(cyl + am): object 'cyl' not found
# Data-masking
with(mtcars, mean(cyl + am))
#> [1] 6.59375
}\if{html}{\out{
}}
While data-masking makes it easy to program interactively with data frames, it makes it harder to create functions. Passing data-masked arguments to functions requires injection with the embracing operator \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}} or, in more complex cases, the injection operator \code{\link{!!}}.
}
\section{Why does data-masking require embracing and injection?}{
Injection (also known as quasiquotation) is a metaprogramming feature that allows you to modify parts of a program. This is needed because under the hood data-masking works by \link[=topic-defuse]{defusing} R code to prevent its immediate evaluation. The defused code is resumed later on in a context where data frame columns are defined.
Let's see what happens when we pass arguments to a data-masking function like \code{summarise()} in the normal way:\if{html}{\out{
}}\preformatted{my_mean <- function(data, var1, var2) \{
dplyr::summarise(data, mean(var1 + var2))
\}
my_mean(mtcars, cyl, am)
#> Error in `dplyr::summarise()`:
#> ! Problem while computing `..1 = mean(var1 + var2)`.
#> Caused by error in `mean()`:
#> ! object 'cyl' not found
}\if{html}{\out{
}}
The problem here is that \code{summarise()} defuses the R code it was supplied, i.e. \code{mean(var1 + var2)}. Instead we want it to see \code{mean(cyl + am)}. This is why we need injection, we need to modify that piece of code by injecting the code supplied to the function in place of \code{var1} and \code{var2}.
To inject a function argument in data-masked context, just embrace it with \verb{\{\{}:\if{html}{\out{
}}
See \ifelse{html}{\link[=topic-data-mask-programming]{Data mask programming patterns}}{\link[=topic-data-mask-programming]{Data mask programming patterns}} to learn more about creating functions around data-masking functions.
}
\section{What does "masking" mean?}{
In normal R programming objects are defined in the current environment, for instance in the global environment or the environment of a function.\if{html}{\out{
}}\preformatted{factor <- 1000
# Can now use `factor` in computations
mean(mtcars$cyl * factor)
#> [1] 6187.5
}\if{html}{\out{
}}
This environment also contains all functions currently in scope. In a script this includes the functions attached with \code{library()} calls; in a package, the functions imported from other packages. If evaluation was performed only in the data frame, we'd lose track of these objects and functions necessary to perform computations.
To keep these objects and functions in scope, the data frame is inserted at the bottom of the current chain of environments. It comes first and has precedence over the user environment. In other words, it \emph{masks} the user environment.
Since masking blends the data and the user environment by giving priority to the former, R can sometimes use a data frame column when you really intended to use a local object.\if{html}{\out{
}}\preformatted{# Defining an env-variable
cyl <- 1000
# Referring to a data-variable
dplyr::summarise(mtcars, mean(cyl))
#> # A tibble: 1 x 1
#> `mean(cyl)`
#>
#> 1 6.19
}\if{html}{\out{
}}
The tidy eval framework provides \link[=.data]{pronouns} to help disambiguate between the mask and user contexts. It is often a good idea to use these pronouns in production code.\if{html}{\out{
}}
Read more about this in \ifelse{html}{\link[=topic-data-mask-ambiguity]{The data mask ambiguity}}{\link[=topic-data-mask-ambiguity]{The data mask ambiguity}}.
}
\section{How does data-masking work?}{
Data-masking relies on three language features:
\itemize{
\item \link[=topic-defuse]{Argument defusal} with \code{\link[=substitute]{substitute()}} (base R) or \code{\link[=enquo]{enquo()}}, \code{\link[=enquos]{enquos()}}, and \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}} (rlang). R code is defused so it can be evaluated later on in a special environment enriched with data.
\item First class environments. Environments are a special type of list-like object in which defused R code can be evaluated. The named elements in an environment define objects. Lists and data frames can be transformed to environments:\if{html}{\out{
}}
\item Explicit evaluation with \code{\link[=eval]{eval()}} (base) or \code{\link[=eval_tidy]{eval_tidy()}} (rlang). When R code is defused, evaluation is interrupted. It can be resumed later on with \code{\link[=eval]{eval()}}:\if{html}{\out{
}}
Evaluation of defused code then occurs in the context of a data mask.
}
}
\section{History}{
The tidyverse embraced the data-masking approach in packages like ggplot2 and dplyr and eventually developed its own programming framework in the rlang package. None of this would have been possible without the following landmark developments from S and R authors.
\itemize{
\item The S language introduced data scopes with \code{\link[=attach]{attach()}} (Becker, Chambers and Wilks, The New S Language, 1988).
\item The S language introduced data-masked formulas in modelling functions (Chambers and Hastie, 1993).
\item Peter Dalgaard (R team) wrote the frametools package in 1997. It was later included in R as \code{\link[base:transform]{base::transform()}} and \code{\link[base:subset]{base::subset()}}. This API is an important source of inspiration for the dplyr package. It was also the first apparition of \emph{selections}, a variant of data-masking extended and codified later on in the \href{https://tidyselect.r-lib.org/articles/syntax.html}{tidyselect package}.
\item In 2000 Luke Tierney (R team) \href{https://github.com/wch/r-source/commit/a945ac8e}{changed formulas} to keep track of their original environments. This change published in R 1.1.0 was a crucial step towards hygienic data masking, i.e. the proper resolution of symbols in their original environments. Quosures were inspired by the environment-tracking mechanism of formulas.
\item Luke introduced \code{\link[base:with]{base::with()}} in 2001.
\item In 2006 the \href{https://r-datatable.com}{data.table package} included data-masking and selections in the \code{i} and \code{j} arguments of the \code{[} method of a data frame.
\item The \href{https://dplyr.tidyverse.org/}{dplyr package} was published in 2014.
\item The rlang package developed tidy eval in 2017 as the data-masking framework of the tidyverse. It introduced the notions of \link[=topic-quosure]{quosure}, \link[=topic-inject]{implicit injection} with \verb{!!} and \verb{!!!}, and \link[=.data]{data pronouns}.
\item In 2019, injection with \verb{\{\{} was introduced in \href{https://www.tidyverse.org/blog/2019/06/rlang-0-4-0/}{rlang 0.4.0} to simplify the defuse-and-inject pattern. This operator allows R programmers to transport data-masked arguments across functions more intuitively and with minimal boilerplate.
}
}
\section{See also}{
\itemize{
\item \ifelse{html}{\link[=topic-data-mask-programming]{Data mask programming patterns}}{\link[=topic-data-mask-programming]{Data mask programming patterns}}
\item \ifelse{html}{\link[=topic-defuse]{Defusing R expressions}}{\link[=topic-defuse]{Defusing R expressions}}
}
}
\keyword{internal}
rlang/man/glue-operators.Rd 0000644 0001762 0000144 00000013506 14175213516 015401 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nse-inject.R
\name{glue-operators}
\alias{glue-operators}
\title{Name injection with \code{"{"} and \code{"{{"}}
\description{
\link[=dyn-dots]{Dynamic dots} (and \link[=topic-data-mask]{data-masked} dots which are dynamic by default) have built-in support for names interpolation with the \href{https://glue.tidyverse.org/}{glue package}.\if{html}{\out{
}}\preformatted{tibble::tibble(foo = 1)
#> # A tibble: 1 x 1
#> foo
#>
#> 1 1
foo <- "name"
tibble::tibble("\{foo\}" := 1)
#> # A tibble: 1 x 1
#> name
#>
#> 1 1
}\if{html}{\out{
}}
Inside functions, embracing an argument with \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}} inserts the expression supplied as argument in the string. This gives an indication on the variable or computation supplied as argument:\if{html}{\out{
}}
Technically, \verb{"\{\{"} \link[=topic-defuse]{defuses} a function argument, calls \code{\link[=as_label]{as_label()}} on the expression supplied as argument, and inserts the result in the string.
\subsection{\verb{"\{"} and \verb{"\{\{"}}{
While \code{glue::glue()} only supports \verb{"\{"}, dynamic dots support both \verb{"\{"} and \verb{"\{\{"}. The double brace variant is similar to the embrace operator \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}} available in \link[=topic-data-mask]{data-masked} arguments.
In the following example, the embrace operator is used in a glue string to name the result with a default name that represents the expression supplied as argument:\if{html}{\out{
}}\preformatted{my_mean <- function(data, var) \{
data \%>\% dplyr::summarise("\{\{ var \}\}" := mean(\{\{ var \}\}))
\}
mtcars \%>\% my_mean(cyl)
#> # A tibble: 1 x 1
#> cyl
#>
#> 1 6.19
mtcars \%>\% my_mean(cyl * am)
#> # A tibble: 1 x 1
#> `cyl * am`
#>
#> 1 2.06
}\if{html}{\out{
}}
\verb{"\{\{"} is only meant for inserting an expression supplied as argument to a function. The result of the expression is not inspected or used. To interpolate a string stored in a variable, use the regular glue operator \verb{"\{"} instead:\if{html}{\out{
}}\preformatted{my_mean <- function(data, var, name = "mean") \{
data \%>\% dplyr::summarise("\{name\}" := mean(\{\{ var \}\}))
\}
mtcars \%>\% my_mean(cyl)
#> # A tibble: 1 x 1
#> mean
#>
#> 1 6.19
mtcars \%>\% my_mean(cyl, name = "cyl")
#> # A tibble: 1 x 1
#> cyl
#>
#> 1 6.19
}\if{html}{\out{
}}
Using the wrong operator causes unexpected results:\if{html}{\out{
}}
Ideally, using \verb{\{\{} on regular objects would be an error. However for technical reasons it is not possible to make a distinction between function arguments and ordinary variables. See \ifelse{html}{\link[=topic-embrace-non-args]{Does \{\{ work on regular objects?}}{\link[=topic-embrace-non-args]{Does curly-curly work on regular objects?}} for more information about this limitation.
}
\subsection{Allow overriding default names}{
The implementation of \code{my_mean()} in the previous section forces a default name onto the result. But what if the caller wants to give it a different name? In functions that take dots, it is possible to just supply a named expression to override the default. In a function like \code{my_mean()} that takes a named argument we need a different approach.
This is where \code{\link[=englue]{englue()}} becomes useful. We can pull out the default name creation in another user-facing argument like this:\if{html}{\out{
}}\preformatted{my_mean <- function(data, var, name = englue("\{\{ var \}\}")) \{
data \%>\% dplyr::summarise("\{name\}" := mean(\{\{ var \}\}))
\}
}\if{html}{\out{
}}
Now the user may supply their own name if needed:\if{html}{\out{
}}\preformatted{mtcars \%>\% my_mean(cyl * am)
#> # A tibble: 1 x 1
#> `cyl * am`
#>
#> 1 2.06
mtcars \%>\% my_mean(cyl * am, name = "mean_cyl_am")
#> # A tibble: 1 x 1
#> mean_cyl_am
#>
#> 1 2.06
}\if{html}{\out{
}}
}
\subsection{What's the deal with \verb{:=}?}{
Name injection in dynamic dots was originally implemented with \verb{:=} instead of \code{=} to allow complex expressions on the LHS:\if{html}{\out{
}}
Name-injection with glue operations was an extension of this existing feature and so inherited the same interface. However, there is no technical barrier to using glue strings on the LHS of \code{=}.
As we are now moving away from \code{\link[=injection-operator]{!!}} for common tasks, we are considering enabling glue strings with \code{=} and superseding \verb{:=} usage. Track the progress of this change in \href{https://github.com/r-lib/rlang/issues/1296}{issue 1296}.
}
\subsection{Using glue syntax in packages}{
Since rlang does not depend directly on glue, you will have to ensure that glue is installed by adding it to your \verb{Imports:} section.\if{html}{\out{
}}
}
}
rlang/man/env_poke.Rd 0000644 0001762 0000144 00000003347 14175213516 014241 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-binding.R
\name{env_poke}
\alias{env_poke}
\title{Poke an object in an environment}
\usage{
env_poke(env = caller_env(), nm, value, inherit = FALSE, create = !inherit)
}
\arguments{
\item{env}{An environment.}
\item{nm}{Names of bindings. \code{nm} must be a single string.}
\item{value}{The value for a new binding.}
\item{inherit}{Whether to look for bindings in the parent
environments.}
\item{create}{Whether to create a binding if it does not already
exist in the environment.}
}
\value{
The old value of \code{nm} or a \link[=zap]{zap sentinel} if the
binding did not exist yet.
}
\description{
\code{env_poke()} will assign or reassign a binding in \code{env} if \code{create}
is \code{TRUE}. If \code{create} is \code{FALSE} and a binding does not already
exists, an error is issued.
}
\details{
If \code{inherit} is \code{TRUE}, the parents environments are checked for
an existing binding to reassign. If not found and \code{create} is
\code{TRUE}, a new binding is created in \code{env}. The default value for
\code{create} is a function of \code{inherit}: \code{FALSE} when inheriting,
\code{TRUE} otherwise.
This default makes sense because the inheriting case is mostly
for overriding an existing binding. If not found, something
probably went wrong and it is safer to issue an error. Note that
this is different to the base R operator \verb{<<-} which will create
a binding in the global environment instead of the current
environment when no existing binding is found in the parents.
}
\seealso{
\code{\link[=env_bind]{env_bind()}} for binding multiple elements. \code{\link[=env_cache]{env_cache()}}
for a variant of \code{env_poke()} designed to cache values.
}
rlang/man/return_from.Rd 0000644 0001762 0000144 00000001657 14175213516 014777 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stack.R
\name{return_from}
\alias{return_from}
\title{Jump to or from a frame}
\usage{
return_from(frame, value = NULL)
}
\arguments{
\item{frame}{An execution environment of a currently running
function.}
\item{value}{The return value.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#questioning}{\figure{lifecycle-questioning.svg}{options: alt='[Questioning]'}}}{\strong{[Questioning]}}
While \code{\link[base:function]{base::return()}} can only return from the current local
frame, \code{return_from()} will return from any frame on the
current evaluation stack, between the global and the currently
active context.
}
\examples{
fn <- function() {
g(current_env())
"ignored"
}
g <- function(env) {
h(env)
"ignored"
}
h <- function(env) {
return_from(env, "early return")
"ignored"
}
fn()
}
\keyword{internal}
rlang/man/rmd/ 0000755 0001762 0000144 00000000000 14176516772 012732 5 ustar ligges users rlang/man/rmd/topic-inject.Rmd 0000644 0001762 0000144 00000012717 14175213516 015763 0 ustar ligges users ```{r, child = "setup.Rmd", include = FALSE}
```
The injection operators are extensions of R implemented by rlang to modify a piece of code before R processes it. There are two main families:
- The [dynamic dots][dyn-dots] operators, [`!!!`] and `r link("'{'")`.
- The [metaprogramming operators][topic-metaprogramming] [`!!`], `r link("{{")`, and `r link("'{{'")`. Splicing with [`!!!`] can also be done in metaprogramming context.
# Dots injection
Unlike regular `...`, [dynamic dots][dyn-dots] are programmable with injection operators.
## Splicing with `!!!`
For instance, take a function like `rbind()` which takes data in `...`. To bind rows, you supply them as separate arguments:
```{r, comment = "#>", collapse = TRUE}
rbind(a = 1:2, b = 3:4)
```
But how do you bind a variable number of rows stored in a list? The base R solution is to invoke `rbind()` with `do.call()`:
```{r, comment = "#>", collapse = TRUE}
rows <- list(a = 1:2, b = 3:4)
do.call("rbind", rows)
```
Functions that implement dynamic dots include a built-in way of folding a list of arguments in `...`. To illustrate this, we'll create a variant of `rbind()` that takes dynamic dots by collecting `...` with [list2()]:
```{r, comment = "#>", collapse = TRUE}
rbind2 <- function(...) {
do.call("rbind", list2(...))
}
```
It can be used just like `rbind()`:
```{r, comment = "#>", collapse = TRUE}
rbind2(a = 1:2, b = 3:4)
```
And a list of arguments can be supplied by _splicing_ the list with [`!!!`]:
```{r, comment = "#>", collapse = TRUE}
rbind2(!!!rows, c = 5:6)
```
## Injecting names with \verb{"\{"}
A related problem comes up when an argument name is stored in a variable. With dynamic dots, you can inject the name using [glue syntax](https://glue.tidyverse.org/) with `r link("'{'")`:
```{r, comment = "#>", collapse = TRUE}
name <- "foo"
rbind2("{name}" := 1:2, bar = 3:4)
rbind2("prefix_{name}" := 1:2, bar = 3:4)
```
# Metaprogramming injection
[Data-masked][topic-data-mask] arguments support the following injection operators. They can also be explicitly enabled with [inject()].
## Embracing with `{{`
The embracing operator `r link("{{")` is made specially for function arguments. It [defuses][topic-defuse] the expression supplied as argument and immediately injects it in place. The injected argument is then evaluated in another context such as a [data mask][topic-data-mask].
```{r, comment = "#>", collapse = TRUE}
# Inject function arguments that might contain
# data-variables by embracing them with {{ }}
mean_by <- function(data, by, var) {
data %>%
dplyr::group_by({{ by }}) %>%
dplyr::summarise(avg = mean({{ var }}, na.rm = TRUE))
}
# The data-variables `cyl` and `disp` inside the
# env-variables `by` and `var` are injected inside `group_by()`
# and `summarise()`
mtcars %>% mean_by(by = cyl, var = disp)
```
Learn more about this pattern in `r link("topic_data_mask_programming")`.
## Injecting with `!!`
Unlike [`!!!`] which injects a list of arguments, the injection operator [`!!`] (pronounced "bang-bang") injects a _single_ object. One use case for `!!` is to substitute an environment-variable (created with `<-`) with a data-variable (inside a data frame).
```{r, comment = "#>", collapse = TRUE}
# The env-variable `var` contains a data-symbol object, in this
# case a reference to the data-variable `height`
var <- data_sym("disp")
# We inject the data-variable contained in `var` inside `summarise()`
mtcars %>%
dplyr::summarise(avg = mean(!!var, na.rm = TRUE))
```
Another use case is to inject a variable by value to avoid [name collisions][topic-data-mask-ambiguity].
```{r, comment = "#>", collapse = TRUE}
df <- data.frame(x = 1)
# This name conflicts with a column in `df`
x <- 100
# Inject the env-variable
df %>%
dplyr::mutate(x = x / !!x)
```
Note that in most cases you don't need injection with `!!`. For instance, the [`.data`] and [`.env`] pronouns provide more intuitive alternatives to injecting a column name and injecting a value.
## Splicing with `!!!`
The splice operator [`!!!`] of dynamic dots can also be used in metaprogramming context (inside [data-masked][topic-data-mask] arguments and inside [inject()]). For instance, we could reimplement the `rbind2()` function presented above using `inject()` instead of `do.call()`:
```r
rbind2 <- function(...) {
inject(rbind(!!!list2(...)))
}
```
There are two things going on here. We collect `...` with [list2()] so that the callers of `rbind2()` may use `!!!`. And we use `inject()` so that `rbind2()` itself may use `!!!` to splice the list of arguments passed to `rbind2()`.
# Injection in other languages
Injection is known as __quasiquotation__ in other programming languages and in computer science. `expr()` is similar to a quasiquotation operator and `!!` is the unquote operator. These terms have a rich history in Lisp languages, and live on in modern languages like [Julia](https://docs.julialang.org/en/v1/manual/metaprogramming/) and [Racket](https://docs.racket-lang.org/reference/quasiquote.html). In base R, quasiquotation is performed with [bquote()].
The main difference between rlang and other languages is that quasiquotation is often implicit instead of explicit. You can use injection operators in any defusing / quoting function (unless that function defuses its argument with a special operator like [enquo0()]). This is not the case in lisp languages for example where injection / unquoting is explicit and only enabled within a backquote.
# See also
- `r link("topic_inject_out_of_context")`
rlang/man/rmd/topic-embrace-constants.Rmd 0000644 0001762 0000144 00000005165 14175213516 020116 0 ustar ligges users ```{r, child = "setup.Rmd", include = FALSE}
```
Function arguments are [defused][topic-defuse] into [quosures][topic-quosure] that keep track of the environment of the defused expression.
```r
quo(1 + 1)
#>
#> expr: ^1 + 1
#> env: global
```
You might have noticed that when constants are supplied, the quosure tracks the empty environment instead of the current environmnent.
```r
quos("foo", 1, NULL)
#> >
#>
#> [[1]]
#>
#> expr: ^"foo"
#> env: empty
#>
#> [[2]]
#>
#> expr: ^1
#> env: empty
#>
#> [[3]]
#>
#> expr: ^NULL
#> env: empty
```
The reason for this has to do with compilation of R code which makes it impossible to consistently capture environments of constants from function arguments. Argument defusing relies on the _promise_ mechanism of R for lazy evaluation of arguments. When functions are compiled and R notices that an argument is constant, it avoids creating a promise since they slow down function evaluation. Instead, the function is directly supplied a naked constant instead of constant wrapped in a promise.
# Concrete case of promise unwrapping by compilation
We can observe this optimisation by calling into the C-level `findVar()` function to capture promises.
```r
# Return the object bound to `arg` without triggering evaluation of
# promises
f <- function(arg) {
rlang:::find_var(current_env(), sym("arg"))
}
# Call `f()` with a symbol or with a constant
g <- function(symbolic) {
if (symbolic) {
f(letters)
} else {
f("foo")
}
}
# Make sure these small functions are compiled
f <- compiler::cmpfun(f)
g <- compiler::cmpfun(g)
```
When `f()` is called with a symbolic argument, we get the promise object created by R.
```r
g(symbolic = TRUE)
#>
```
However, supplying a constant to `"f"` returns the constant directly.
```r
g(symbolic = FALSE)
#> [1] "foo"
```
Without a promise, there is no way to figure out the original environment of an argument.
# Do we need environments for constants?
Data-masking APIs in the tidyverse are intentionally designed so that they don't need an environment for constants.
- Data-masking APIs should be able to interpret constants. These can arise from normal argument passing as we have seen, or by [injection][topic-inject] with `!!`. There should be no difference between `dplyr::mutate(mtcars, var = cyl)` and `dplyr::mutate(mtcars, var = !!mtcars$cyl)`.
- Data-masking is an _evaluation_ idiom, not an _introspective_ one. The behaviour of data-masking function should not depend on the calling environment when a constant (or a symbol evaluating to a given value) is supplied.
rlang/man/rmd/topic-embrace-non-args.Rmd 0000644 0001762 0000144 00000001740 14175213516 017621 0 ustar ligges users ```{r, child = "setup.Rmd", include = FALSE}
```
The embrace operator `r link("{{")` should be used exclusively with function arguments:
```r
fn <- function(arg) {
quo(foo({{ arg }}))
}
fn(1 + 1)
#>
#> expr: ^foo(^1 + 1)
#> env: 0x7ffd89aac518
```
However you may have noticed that it also works on regular objects:
```r
fn <- function(arg) {
arg <- force(arg)
quo(foo({{ arg }}))
}
fn(1 + 1)
#>
#> expr: ^foo(^2)
#> env: 0x7ffd8a633398
```
In that case, `{{` captures the _value_ of the expression instead of a defused expression. That's because only function arguments can be defused.
Note that this issue also applies to [enquo()] (on which `{{` is based).
# Why is this not an error?
Ideally we would have made `{{` on regular objects an error. However this is not possible because in compiled R code it is not always possible to distinguish a regular variable from a function argument. See `r link("topic_embrace_constants")` for more about this.
rlang/man/rmd/topic-multiple-columns.Rmd 0000644 0001762 0000144 00000012020 14175213516 020003 0 ustar ligges users ```{r, child = "setup.Rmd", include = FALSE}
```
In this guide we compare ways of taking multiple columns in a single function argument.
As a refresher (see the [programming patterns][topic-data-mask-programming] article), there are two common ways of passing arguments to [data-masking][topic-data-mask] functions. For single arguments, embrace with `r link("{{")`:
```{r, comment = "#>", collapse = TRUE}
my_group_by <- function(data, var) {
data %>% dplyr::group_by({{ var }})
}
my_pivot_longer <- function(data, var) {
data %>% tidyr::pivot_longer({{ var }})
}
```
For multiple arguments in `...`, pass them on to functions that also take `...` like `group_by()`, or pass them within `c()` for functions taking tidy selection in a single argument like `pivot_longer()`:
```{r, comment = "#>", collapse = TRUE}
# Pass dots through
my_group_by <- function(.data, ...) {
.data %>% dplyr::group_by(...)
}
my_pivot_longer <- function(.data, ...) {
.data %>% tidyr::pivot_longer(c(...))
}
```
But what if you want to take multiple columns in a single named argument rather than in `...`?
# Using tidy selections
The idiomatic tidyverse way of taking multiple columns in a single argument is to take a _tidy selection_ (see the [Argument behaviours][topic-data-mask-programming] section). In tidy selections, the syntax for passing multiple columns in a single argument is `c()`:
```r
mtcars %>% tidyr::pivot_longer(c(am, cyl, vs))
```
Since `{{` inherits behaviour, this implementation of `my_pivot_longer()` automatically allows multiple columns passing:
```r
my_pivot_longer <- function(data, var) {
data %>% tidyr::pivot_longer({{ var }})
}
mtcars %>% my_pivot_longer(c(am, cyl, vs))
```
For `group_by()`, which takes data-masked arguments, we'll use `across()` as a _bridge_ (see [Bridge patterns][topic-data-mask-programming]).
```r
my_group_by <- function(data, var) {
data %>% dplyr::group_by(across({{ var }}))
}
mtcars %>% my_group_by(c(am, cyl, vs))
```
When embracing in tidyselect context or using `across()` is not possible, you might have to implement tidyselect behaviour manually with `tidyselect::eval_select()`.
# Using external defusal
To implement an argument with tidyselect behaviour, it is necessary to [defuse][topic-defuse] the argument. However defusing an argument which had historically behaved like a regular argument is a rather disruptive breaking change. This is why we could not implement tidy selections in ggplot2 facetting functions like `facet_grid()` and `facet_wrap()`.
An alternative is to use external defusal of arguments. This is what formula interfaces do for instance. A modelling function takes a formula in a regular argument and the formula defuses the user code:
```r
my_lm <- function(data, f, ...) {
lm(f, data, ...)
}
mtcars %>% my_lm(disp ~ drat)
```
Once created, the defused expressions contained in the formula are passed around like a normal argument. A similar approach was taken to update `facet_` functions to tidy eval. The `vars()` function (a simple alias to [quos()]) is provided so that users can defuse their arguments externally.
```r
ggplot2::facet_grid(
ggplot2::vars(cyl),
ggplot2::vars(am, vs)
)
```
You can implement this approach by simply taking a list of defused expressions as argument. This list can be passed the usual way to other functions taking such lists:
```r
my_facet_grid <- function(rows, cols, ...) {
ggplot2::facet_grid(rows, cols, ...)
}
```
Or it can be spliced with [`!!!`]:
```r
my_group_by <- function(data, vars) {
stopifnot(is_quosures(vars))
data %>% dplyr::group_by(!!!vars)
}
mtcars %>% my_group_by(dplyr::vars(cyl, am))
```
# A non-approach: Parsing lists
Intuitively, many programmers who want to take a list of expressions in a single argument try to defuse an argument and parse it. The user is expected to supply multiple arguments within a `list()` expression. When such a call is detected, the arguments are retrieved and spliced with `!!!`. Otherwise, the user is assumed to have supplied a single argument which is injected with `!!`. An implementation along these lines might look like this:
```{r, comment = "#>", collapse = TRUE}
my_group_by <- function(data, vars) {
vars <- enquo(vars)
if (quo_is_call(vars, "list")) {
expr <- quo_get_expr(vars)
env <- quo_get_env(vars)
args <- as_quosures(call_args(expr), env = env)
data %>% dplyr::group_by(!!!args)
} else {
data %>% dplyr::group_by(!!vars)
}
}
```
This does work in simple cases:
```{r, comment = "#>", collapse = TRUE}
mtcars %>% my_group_by(cyl) %>% dplyr::group_vars()
mtcars %>% my_group_by(list(cyl, am)) %>% dplyr::group_vars()
```
However this parsing approach quickly shows limits:
```r
mtcars %>% my_group_by(list2(cyl, am))
#> Error in `group_by()`: Can't add columns.
#> ℹ `..1 = list2(cyl, am)`.
#> ℹ `..1` must be size 32 or 1, not 2.
```
Also, it would be better for overall consistency of interfaces to use the tidyselect syntax `c()` for passing multiple columns. In general, we recommend to use either the tidyselect or the external defusal approaches.
rlang/man/rmd/topic-metaprogramming.Rmd 0000644 0001762 0000144 00000024602 14175213516 017674 0 ustar ligges users ```{r, child = "setup.Rmd", include = FALSE}
```
The patterns covered in this article rely on _metaprogramming_, the ability to defuse, create, expand, and inject R expressions. A good place to start if you're new to programming on the language is the [Metaprogramming chapter](https://adv-r.hadley.nz/metaprogramming.html) of the [Advanced R](https://adv-r.hadley.nz) book.
If you haven't already, read `r link("topic_data_mask_programming")` which covers simpler patterns that do not require as much theory to get up to speed. It covers concepts like argument behaviours and the various patterns you can add to your toolbox (forwarding, names, bridge, and transformative patterns).
# Forwarding patterns
## Defuse and inject
`r link("{{")` and `...` are sufficient for most purposes. Sometimes however, it is necessary to decompose the forwarding action into its two constitutive steps, [defusing][topic-defuse] and [injecting][topic-inject].
`{{` is the combination of [enquo()] and [`!!`][injection-operator]. These functions are completely equivalent:
```r
my_summarise <- function(data, var) {
data %>% dplyr::summarise({{ var }})
}
my_summarise <- function(data, var) {
data %>% dplyr::summarise(!!enquo(var))
}
```
Passing `...` is equivalent to the combination of [enquos()] and [`!!!`][splice-operator]:
```r
my_group_by <- function(.data, ...) {
.data %>% dplyr::group_by(...)
}
my_group_by <- function(.data, ...) {
.data %>% dplyr::group_by(!!!enquos(...))
}
```
The advantage of decomposing the steps is that you gain access to the [defused expressions][topic-defuse]. Once defused, you can inspect or modify the expressions before injecting them in their target context.
## Inspecting input labels
For instance, here is how to create an automatic name for a defused argument using [as_label()]:
```{r, comment = "#>", collapse = TRUE}
f <- function(var) {
var <- enquo(var)
as_label(var)
}
f(cyl)
f(1 + 1)
```
This is essentially equivalent to formatting an argument using [englue()]:
```{r}
f2 <- function(var) {
englue("{{ var }}")
}
f2(1 + 1)
```
With multiple arguments, use the plural variant [enquos()]. Set `.named` to `TRUE` to automatically call [as_label()] on the inputs for which the user has not provided a name (the same behaviour as in most dplyr verbs):
```{r, comment = "#>", collapse = TRUE}
g <- function(...) {
vars <- enquos(..., .named = TRUE)
names(vars)
}
g(cyl, 1 + 1)
```
Just like with `dplyr::mutate()`, the user can override automatic names by supplying explicit names:
```{r, comment = "#>", collapse = TRUE}
g(foo = cyl, bar = 1 + 1)
```
Defuse-and-inject patterns are most useful for transforming inputs. Some applications are explored in the Transformation patterns section.
# Names patterns
## Symbolise and inject
The symbolise-and-inject pattern is a _names pattern_ that you can use when `across(all_of())` is not supported. It consists in creating [defused expressions][topic-defuse] that refer to the data-variables represented in the names vector. These are then injected in the data mask context.
Symbolise a single string with [sym()] or [data_sym()]:
```{r, comment = "#>", collapse = TRUE}
var <- "cyl"
sym(var)
data_sym(var)
```
Symbolise a character vector with [syms()] or [data_syms()].
```{r, comment = "#>", collapse = TRUE}
vars <- c("cyl", "am")
syms(vars)
data_syms(vars)
```
Simple symbols returned by `sym()` and `syms()` work in a wider variety of cases (with base functions in particular) but we'll use mostly use `data_sym()` and `data_syms()` because they are more robust (see `r link("topic_data_mask_ambiguity")`). Note that these do not return _symbols_ per se, instead they create _calls_ to `$` that subset the [`.data`] pronoun.
Since the `.data` pronoun is a tidy eval feature, you can't use it in base functions. As a rule, prefer the `data_`-prefixed variants when you're injecting in tidy eval functions and the unprefixed functions for base functions.
A list of symbols can be injected in data-masked dots with the splice operator [`!!!`][splice-operator], which injects each element of the list as a separate argument. For instance, to implement a `group_by()` variant that takes a character vector of column names, you might write:
```r
my_group_by <- function(data, vars) {
data %>% dplyr::group_by(!!!data_syms(vars))
}
my_group_by(vars)
```
In more complex case, you might want to add R code around the symbols. This requires _transformation_ patterns, see the section below.
# Bridge patterns
## `mutate()` as a data-mask to selection bridge
This is a variant of the `transmute()` bridge pattern described in `r link("topic_data_mask_programming")` that does not materialise `...` in the intermediate step. Instead, the `...` expressions are defused and inspected. Then the expressions, rather than the columns, are spliced in `mutate()`.
```r
my_pivot_longer <- function(data, ...) {
# Defuse the dots and inspect the names
dots <- enquos(..., .named = TRUE)
names <- names(dots)
# Pass the inputs to `mutate()`
data <- data %>% dplyr::mutate(!!!dots)
# Select `...` inputs by name with `all_of()`
data %>%
tidyr::pivot_longer(cols = all_of(names))
}
mtcars %>% my_pivot_longer(cyl, am = am * 100)
```
1. Defuse the `...` expressions. The `.named` argument ensures unnamed inputs get a default name, just like they would if passed to `mutate()`. Take the names of the list of inputs.
2. Once we have the names, inject the argument expressions into `mutate()` to update the data frame.
3. Finally, pass the names to the tidy selection via [`all_of()`](https://tidyselect.r-lib.org/reference/all_of.html).
# Transformation patterns
## Transforming inputs manually
If `across()` and variants are not available, you will need to transform the inputs yourself using metaprogramming techniques. To illustrate the technique we'll reimplement `my_mean()` and without using `across()`. The pattern consists in defusing the input expression, building larger calls around them, and finally inject the modified expressions inside the data-masking functions.
We'll start with a single named argument for simplicity:
```{r, comment = "#>", collapse = TRUE}
my_mean <- function(data, var) {
# Defuse the expression
var <- enquo(var)
# Wrap it in a call to `mean()`
var <- expr(mean(!!var, na.rm = TRUE))
# Inject the expanded expression
data %>% dplyr::summarise(mean = !!var)
}
mtcars %>% my_mean(cyl)
```
With `...` the technique is similar, though a little more involved. We'll use the plural variants `enquos()` and [`!!!`]. We'll also loop over the variable number of inputs using `purrr::map()`. But the pattern is otherwise basically the same:
```{r, comment = "#>", collapse = TRUE}
my_mean <- function(.data, ...) {
# Defuse the dots. Make sure they are automatically named.
vars <- enquos(..., .named = TRUE)
# Map over each defused expression and wrap it in a call to `mean()`
vars <- purrr::map(vars, ~ expr(mean(!!.x, na.rm = TRUE)))
# Inject the expressions
.data %>% dplyr::summarise(!!!vars)
}
mtcars %>% my_mean(cyl)
```
Note that we are inheriting the data-masking behaviour of `summarise()` because we have effectively forwarded `...` inside that verb. This is different than transformation patterns based on `across()` which inherit tidy selection behaviour. In practice, this means the function doesn't support selection helpers and syntax. Instead, it gains the ability to create new vectors on the fly:
```{r, comment = "#>", collapse = TRUE}
mtcars %>% my_mean(cyl = cyl * 100)
```
# Base patterns
In this section, we review patterns for programming with _base_ data-masking functions. They essentially consist in building and evaluating expressions in the data mask. We review these patterns and compare them to rlang idioms.
## Data-masked `get()`
In the simplest version of this pattern, `get()` is called with a variable name to retrieve objects from the data mask:
```{r, comment = "#>", collapse = TRUE}
var <- "cyl"
with(mtcars, mean(get(var)))
```
This sort of pattern is susceptible to [names collisions][topic-data-mask-ambiguity]. For instance, the input data frame might contain a variable called `var`:
```{r, comment = "#>", collapse = TRUE, error = TRUE}
df <- data.frame(var = "wrong")
with(df, mean(get(var)))
```
In general, prefer symbol injection over `get()` to prevent this sort of collisions. With base functions you will need to enable injection operators explicitly using [inject()]:
```{r, comment = "#>", collapse = TRUE}
inject(
with(mtcars, mean(!!sym(var)))
)
```
See `r link("topic_data_mask_ambiguity")` for more information about names collisions.
## Data-masked `parse()` and `eval()`
A more involved pattern consists in building R code in a string and evaluating it in the mask:
```{r, comment = "#>", collapse = TRUE}
var1 <- "am"
var2 <- "vs"
code <- paste(var1, "==", var2)
with(mtcars, mean(eval(parse(text = code))))
```
As before, the `code` variable is vulnerable to [names collisions][topic-data-mask-ambiguity]. More importantly, if `var1` and `var2` are user inputs, they could contain [adversarial code](https://xkcd.com/327/). Evaluating code assembled from strings is always a risky business:
```r
var1 <- "(function() {
Sys.sleep(Inf) # Could be a coin mining routine
})()"
var2 <- "vs"
code <- paste(var1, "==", var2)
with(mtcars, mean(eval(parse(text = code))))
```
This is not a big deal if your code is only used internally. However, this code could be part of a public Shiny app which Internet users could exploit. But even internally, parsing is a source of bugs when variable names contain syntactic symbols like `-` or `:`.
```{r, comment = "#>", collapse = TRUE, error = TRUE}
var1 <- ":var:"
var2 <- "vs"
code <- paste(var1, "==", var2)
with(mtcars, mean(eval(parse(text = code))))
```
For these reasons, always prefer to _build_ code instead of parsing code. Building variable names with [sym()] is a way of sanitising inputs.
```{r, comment = "#>", collapse = TRUE}
var1 <- "(function() {
Sys.sleep(Inf) # Could be a coin mining routine
})()"
var2 <- "vs"
code <- call("==", sym(var1), sym(var2))
code
```
The adversarial input now produces an error:
```{r, comment = "#>", collapse = TRUE, error = TRUE}
with(mtcars, mean(eval(code)))
```
Finally, it is recommended to inject the code instead of evaluating it to avoid names collisions:
```{r, comment = "#>", collapse = TRUE}
var1 <- "am"
var2 <- "vs"
code <- call("==", sym(var1), sym(var2))
inject(
with(mtcars, mean(!!code))
)
```
rlang/man/rmd/glue-operators.Rmd 0000644 0001762 0000144 00000010307 14175213516 016334 0 ustar ligges users ```{r, child = "setup.Rmd", include = FALSE}
```
[Dynamic dots][dyn-dots] (and [data-masked][topic-data-mask] dots which are dynamic by default) have built-in support for names interpolation with the [glue package](https://glue.tidyverse.org/).
```{r, comment = "#>", collapse = TRUE}
tibble::tibble(foo = 1)
foo <- "name"
tibble::tibble("{foo}" := 1)
```
Inside functions, embracing an argument with `r link("{{")` inserts the expression supplied as argument in the string. This gives an indication on the variable or computation supplied as argument:
```{r, comment = "#>", collapse = TRUE}
tib <- function(x) {
tibble::tibble("var: {{ x }}" := x)
}
tib(1 + 1)
```
See also [englue()] to string-embrace outside of dynamic dots.
```{r, comment = "#>", collapse = TRUE}
g <- function(x) {
englue("var: {{ x }}")
}
g(1 + 1)
```
Technically, `r text("'{{'")` [defuses][topic-defuse] a function argument, calls [as_label()] on the expression supplied as argument, and inserts the result in the string.
## `r text("'{'")` and `r text("'{{'")`
While `glue::glue()` only supports `r text("'{'")`, dynamic dots support both `r text("'{'")` and `r text("'{{'")`. The double brace variant is similar to the embrace operator `r link("{{")` available in [data-masked][topic-data-mask] arguments.
In the following example, the embrace operator is used in a glue string to name the result with a default name that represents the expression supplied as argument:
```{r, comment = "#>", collapse = TRUE}
my_mean <- function(data, var) {
data %>% dplyr::summarise("{{ var }}" := mean({{ var }}))
}
mtcars %>% my_mean(cyl)
mtcars %>% my_mean(cyl * am)
```
`r text("'{{'")` is only meant for inserting an expression supplied as argument to a function. The result of the expression is not inspected or used. To interpolate a string stored in a variable, use the regular glue operator `r text("'{'")` instead:
```{r, comment = "#>", collapse = TRUE}
my_mean <- function(data, var, name = "mean") {
data %>% dplyr::summarise("{name}" := mean({{ var }}))
}
mtcars %>% my_mean(cyl)
mtcars %>% my_mean(cyl, name = "cyl")
```
Using the wrong operator causes unexpected results:
```{r, comment = "#>", collapse = TRUE}
x <- "name"
list2("{{ x }}" := 1)
list2("{x}" := 1)
```
Ideally, using `{{` on regular objects would be an error. However for technical reasons it is not possible to make a distinction between function arguments and ordinary variables. See `r link("topic_embrace_non_args")` for more information about this limitation.
## Allow overriding default names
The implementation of `my_mean()` in the previous section forces a default name onto the result. But what if the caller wants to give it a different name? In functions that take dots, it is possible to just supply a named expression to override the default. In a function like `my_mean()` that takes a named argument we need a different approach.
This is where [englue()] becomes useful. We can pull out the default name creation in another user-facing argument like this:
```{r, comment = "#>", collapse = TRUE}
my_mean <- function(data, var, name = englue("{{ var }}")) {
data %>% dplyr::summarise("{name}" := mean({{ var }}))
}
```
Now the user may supply their own name if needed:
```{r, comment = "#>", collapse = TRUE}
mtcars %>% my_mean(cyl * am)
mtcars %>% my_mean(cyl * am, name = "mean_cyl_am")
```
## What's the deal with `:=`?
Name injection in dynamic dots was originally implemented with `:=` instead of `=` to allow complex expressions on the LHS:
```{r, comment = "#>", collapse = TRUE}
x <- "name"
list2(!!x := 1)
```
Name-injection with glue operations was an extension of this existing feature and so inherited the same interface. However, there is no technical barrier to using glue strings on the LHS of `=`.
As we are now moving away from [`!!`][injection-operator] for common tasks, we are considering enabling glue strings with `=` and superseding `:=` usage. Track the progress of this change in [issue 1296](https://github.com/r-lib/rlang/issues/1296).
## Using glue syntax in packages
Since rlang does not depend directly on glue, you will have to ensure that glue is installed by adding it to your `Imports:` section.
```r
usethis::use_package("glue", "Imports")
```
rlang/man/rmd/topic-data-mask-programming.Rmd 0000644 0001762 0000144 00000032606 14176516772 020703 0 ustar ligges users ```{r, child = "setup.Rmd", include = FALSE}
```
[Data-masking][topic-data-mask] functions require special programming patterns when used inside other functions. In this topic we'll review and compare the different patterns that can be used to solve specific problems.
If you are a beginner, you might want to start with one of these tutorials:
- [Programming with dplyr](https://dplyr.tidyverse.org/articles/programming.html)
- [Using ggplot2 in packages](https://ggplot2.tidyverse.org/articles/ggplot2-in-packages.html)
If you'd like to go further and learn about defusing and injecting expressions, read the [metaprogramming patterns topic][topic-metaprogramming].
# Choosing a pattern
Two main considerations determine which programming pattern you need to wrap a data-masking function:
1. What behaviour does the _wrapped_ function implement?
2. What behaviour should _your_ function implement?
Depending on the answers to these questions, you can choose between these approaches:
- The __forwarding patterns__ with which your function inherits the behaviour of the function it interfaces with.
- The __name patterns__ with which your function takes strings or character vectors of column names.
- The __bridge patterns__ with which you change the behaviour of an argument instead of inheriting it.
You will also need to use different solutions for single named arguments than for multiple arguments in `...`.
# Argument behaviours
In a regular function, arguments can be defined in terms of a _type_ of objects that they accept. An argument might accept a character vector, a data frame, a single logical value, etc. Data-masked arguments are more complex. Not only do they generally accept a specific type of objects (for instance `dplyr::mutate()` accepts vectors), they exhibit special computational behaviours.
- Data-masked expressions (base): E.g. [transform()], [with()]. Expressions may refer to the columns of the supplied data frame.
- Data-masked expressions (tidy eval): E.g. `dplyr::mutate()`, `ggplot2::aes()`. Same as base data-masking but with tidy eval features enabled. This includes [injection operators][topic-inject] such as `r link("{{")` and [`!!`][injection-operator] and the [`.data`] and [`.env`] pronouns.
- Data-masked symbols: Same as data-masked arguments but the supplied expressions must be simple column names. This often simplifies things, for instance this is an easy way of avoiding issues of [double evaluation][topic-double-evaluation].
- [Tidy selections](https://tidyselect.r-lib.org/reference/language.html): E.g. `dplyr::select()`, `tidyr::pivot_longer()`. This is an alternative to data masking that supports selection helpers like `starts_with()` or `all_of()`, and implements special behaviour for operators like `c()`, `|` and `&`.
Unlike data masking, tidy selection is an interpreted dialect. There is in fact no masking at all. Expressions are either interpreted in the context of the data frame (e.g. `c(cyl, am)` which stands for the union of the columns `cyl` and `am`), or evaluated in the user environment (e.g. `all_of()`, `starts_with()`, and any other expressions). This has implications for inheritance of argument behaviour as we will see below.
- [Dynamic dots][doc_dots_dynamic]: These may be data-masked arguments, tidy selections, or just regular arguments. Dynamic dots support injection of multiple arguments with the [`!!!`][splice-operator] operator as well as name injection with [glue][glue-operators] operators.
To let users know about the capabilities of your function arguments, document them with the following tags, depending on which set of semantics they inherit from:
```
@param foo <[`data-masked`][dplyr::dplyr_data_masking]> What `foo` does.
@param bar <[`tidy-select`][dplyr::dplyr_tidy_select]> What `bar` does.
@param ... <[`dynamic-dots`][rlang::dyn-dots]> What these dots do.
```
# Forwarding patterns
With the forwarding patterns, arguments inherit the behaviour of the data-masked arguments they are passed in.
## Embrace with `{{`
The embrace operator `r link("{{")` is a forwarding syntax for single arguments. You can forward an argument in data-masked context:
```r
my_summarise <- function(data, var) {
data %>% dplyr::summarise({{ var }})
}
```
Or in tidyselections:
```r
my_pivot_longer <- function(data, var) {
data %>% tidyr::pivot_longer(cols = {{ var }})
}
```
The function automatically inherits the behaviour of the surrounding context. For instance arguments forwarded to a data-masked context may refer to columns or use the [`.data`] pronoun:
```r
mtcars %>% my_summarise(mean(cyl))
x <- "cyl"
mtcars %>% my_summarise(mean(.data[[x]]))
```
And arguments forwarded to a tidy selection may use all tidyselect features:
```r
mtcars %>% my_pivot_longer(cyl)
mtcars %>% my_pivot_longer(vs:gear)
mtcars %>% my_pivot_longer(starts_with("c"))
x <- c("cyl", "am")
mtcars %>% my_pivot_longer(all_of(x))
```
## Forward `...`
Simple forwarding of `...` arguments does not require any special syntax since dots are already a forwarding syntax. Just pass them to another function like you normally would. This works with data-masked arguments:
```r
my_group_by <- function(.data, ...) {
.data %>% dplyr::group_by(...)
}
mtcars %>% my_group_by(cyl = cyl * 100, am)
```
As well as tidy selections:
```r
my_select <- function(.data, ...) {
.data %>% dplyr::select(...)
}
mtcars %>% my_select(starts_with("c"), vs:carb)
```
Some functions take a tidy selection in a single named argument. In that case, pass the `...` inside `c()`:
```r
my_pivot_longer <- function(.data, ...) {
.data %>% tidyr::pivot_longer(c(...))
}
mtcars %>% my_pivot_longer(starts_with("c"), vs:carb)
```
Inside a tidy selection, `c()` is not a vector concatenator but a selection combinator. This makes it handy to interface between functions that take `...` and functions that take a single argument.
# Names patterns
With the names patterns you refer to columns by name with strings or character vectors stored in env-variables. Whereas the forwarding patterns are exclusively used within a function to pass _arguments_, the names patterns can be used anywhere.
- In a script, you can loop over a character vector with `for` or `lapply()` and use the [`.data`] pattern to connect a name to its data-variable. A vector can also be supplied all at once to the tidy select helper `all_of()`.
- In a function, using the names patterns on function arguments lets users supply regular data-variable names without any of the complications that come with data-masking.
## Subsetting the `.data` pronoun
The [`.data`] pronoun is a tidy eval feature that is enabled in all data-masked arguments, just like `r link("{{")`. The pronoun represents the data mask and can be subsetted with `[[` and `$`. These three statements are equivalent:
```r
mtcars %>% dplyr::summarise(mean = mean(cyl))
mtcars %>% dplyr::summarise(mean = mean(.data$cyl))
var <- "cyl"
mtcars %>% dplyr::summarise(mean = mean(.data[[var]]))
```
The `.data` pronoun can be subsetted in loops:
```{r, comment = "#>", collapse = TRUE}
vars <- c("cyl", "am")
for (var in vars) print(dplyr::summarise(mtcars, mean = mean(.data[[var]])))
purrr::map(vars, ~ dplyr::summarise(mtcars, mean = mean(.data[[.x]])))
```
And it can be used to connect function arguments to a data-variable:
```{r, comment = "#>", collapse = TRUE}
my_mean <- function(data, var) {
data %>% dplyr::summarise(mean = mean(.data[[var]]))
}
my_mean(mtcars, "cyl")
```
With this implementation, `my_mean()` is completely insulated from data-masking behaviour and is called like an ordinary function.
```{r, comment = "#>", collapse = TRUE}
# No masking
am <- "cyl"
my_mean(mtcars, am)
# Programmable
my_mean(mtcars, tolower("CYL"))
```
## Character vector of names
The `.data` pronoun can only be subsetted with single column names. It doesn't support single-bracket indexing:
```{r, comment = "#>", collapse = TRUE, error = TRUE}
mtcars %>% dplyr::summarise(.data[c("cyl", "am")])
```
There is no plural variant of `.data` built in tidy eval. Instead, we'll used the `all_of()` operator available in tidy selections to supply character vectors. This is straightforward in functions that take tidy selections, like `tidyr::pivot_longer()`:
```{r, comment = "#>", collapse = TRUE}
vars <- c("cyl", "am")
mtcars %>% tidyr::pivot_longer(all_of(vars))
```
If the function does not take a tidy selection, it might be possible to use a _bridge pattern_. This option is presented in the bridge section below. If a bridge is impossible or inconvenient, a little metaprogramming with the [symbolise-and-inject pattern][topic-metaprogramming] can help.
# Bridge patterns
Sometimes the function you are calling does not implement the behaviour you would like to give to the arguments of your function. To work around this may require a little thought since there is no systematic way of turning one behaviour into another. The general technique consists in forwarding the arguments inside a context that implements the behaviour that you want. Then, find a way to bridge the result to the target verb or function.
## `across()` as a selection to data-mask bridge
dplyr 1.0 added support for tidy selections in all verbs via `across()`. This function is normally used for mapping over columns but can also be used to perform a simple selection. For instance, if you'd like to pass an argument to `group_by()` with a tidy-selection interface instead of a data-masked one, use `across()` as a bridge:
```r
my_group_by <- function(data, var) {
data %>% dplyr::group_by(across({{ var }}))
}
mtcars %>% my_group_by(starts_with("c"))
```
Since `across()` takes selections in a single argument (unlike `select()` which takes multiple arguments), you can't directly pass `...`. Instead, take them within `c()`, which is the tidyselect way of supplying multiple selections within a single argument:
```r
my_group_by <- function(.data, ...) {
.data %>% dplyr::group_by(across(c(...)}))
}
mtcars %>% my_group_by(starts_with("c"), vs:gear)
```
## `across(all_of())` as a names to data mask bridge
If instead of forwarding variables in `across()` you pass them to `all_of()`, you create a names to data mask bridge.
```r
my_group_by <- function(data, vars) {
data %>% dplyr::group_by(across(all_of(vars)))
}
mtcars %>% my_group_by(c("cyl", "am"))
```
Use this bridge technique to connect vectors of names to a data-masked context.
## `transmute()` as a data-mask to selection bridge
Passing data-masked arguments to a tidy selection is a little more tricky and requires a three step process.
```r
my_pivot_longer <- function(data, ...) {
# Forward `...` in data-mask context with `transmute()`
# and save the inputs names
inputs <- dplyr::transmute(data, ...)
names <- names(inputs)
# Update the data with the inputs
data <- dplyr::mutate(data, !!!inputs)
# Select the inputs by name with `all_of()`
tidyr::pivot_longer(data, cols = all_of(names))
}
mtcars %>% my_pivot_longer(cyl, am = am * 100)
```
1. In a first step we pass the `...` expressions to `transmute()`. Unlike `mutate()`, it creates a new data frame from the user inputs. The only goal of this step is to inspect the names in `...`, including the default names created for unnamed arguments.
2. Once we have the names, we inject the arguments into `mutate()` to update the data frame.
3. Finally, we pass the names to the tidy selection via [`all_of()`](https://tidyselect.r-lib.org/reference/all_of.html).
# Transformation patterns
## Named inputs versus `...`
In the case of a named argument, transformation is easy. We simply surround the embraced input it in R code. For instance, the `my_summarise()` function is not exactly useful compared to just calling `summarise()`:
```r
my_summarise <- function(data, var) {
data %>% dplyr::summarise({{ var }})
}
```
We can make it more useful by adding code around the variable:
```r
my_mean <- function(data, var) {
data %>% dplyr::summarise(mean = mean({{ var }}, na.rm = TRUE))
}
```
For inputs in `...` however, this technique does not work. We would need some kind of templating syntax for dots that lets us specify R code with a placeholder for the dots elements. This isn't built in tidy eval but you can use operators like `dplyr::across()`, `dplyr::if_all()`, or `dplyr::if_any()`. When that isn't possible, you can template the expression manually.
## Transforming inputs with `across()`
The `across()` operation in dplyr is a convenient way of mapping an expression across a set of inputs. We will create a variant of `my_mean()` that computes the `mean()` of all arguments supplied in `...`. The easiest way it to forward the dots to `across()` (which causes `...` to inherit its tidy selection behaviour):
```{r, comment = "#>", collapse = TRUE}
my_mean <- function(data, ...) {
data %>% dplyr::summarise(across(c(...), ~ mean(.x, na.rm = TRUE)))
}
mtcars %>% my_mean(cyl, carb)
mtcars %>% my_mean(foo = cyl, bar = carb)
mtcars %>% my_mean(starts_with("c"), mpg:disp)
```
## Transforming inputs with `if_all()` and `if_any()`
`dplyr::filter()` requires a different operation than `across()` because it needs to combine the logical expressions with `&` or `|`. To solve this problem dplyr introduced the `if_all()` and `if_any()` variants of `across()`.
In the following example, we filter all rows for which a set of variables are not equal to their minimum value:
```r
filter_non_baseline <- function(.data, ...) {
.data %>% dplyr::filter(if_all(c(...), ~ .x != min(.x, na.rm = TRUE)))
}
mtcars %>% filter_non_baseline(vs, am, gear)
```
rlang/man/rmd/topic-quosure.Rmd 0000644 0001762 0000144 00000017440 14175213516 016210 0 ustar ligges users ```{r, child = "setup.Rmd", include = FALSE}
```
A quosure is a special type of [defused expression][topic-defuse] that keeps track of the original context the expression was written in. The tracking capabilities of quosures is important when interfacing [data-masking][topic-data-mask] functions together because the functions might come from two unrelated environments, like two different packages.
# Blending environments
Let's take an example where the R user calls the function `summarise_bmi()` from the foo package to summarise a data frame with statistics of a BMI value. Because the `height` variable of their data frame is not in metres, they use a custom function `div100()` to rescale the column.
```r
# Global environment of user
div100 <- function(x) {
x / 100
}
dplyr::starwars %>%
foo::summarise_bmi(mass, div100(height))
```
The `summarise_bmi()` function is a data-masking function defined in the namespace of the foo package which looks like this:
```r
# Namespace of package foo
bmi <- function(mass, height) {
mass / height^2
}
summarise_bmi <- function(data, mass, height) {
data %>%
bar::summarise_stats(bmi({{ mass }}, {{ height }}))
}
```
The foo package uses the custom function `bmi()` to perform a computation on two vectors. It interfaces with `summarise_stats()` defined in bar, another package whose namespace looks like this:
```r
# Namespace of package bar
check_numeric <- function(x) {
stopifnot(is.numeric(x))
x
}
summarise_stats <- function(data, var) {
data %>%
dplyr::transmute(
var = check_numeric({{ var }})
) %>%
dplyr::summarise(
mean = mean(var, na.rm = TRUE),
sd = sd(var, na.rm = TRUE)
)
}
```
Again the package bar uses a custom function, `check_numeric()`, to validate its input. It also interfaces with data-masking functions from dplyr (using the [define-a-constant][topic-double-evaluation] trick to avoid issues of double evaluation).
There are three data-masking functions simultaneously interfacing in this snippet:
- At the bottom, `dplyr::transmute()` takes a data-masked input, and creates a data frame of a single column named `var`.
- Before this, `bar::summarise_stats()` takes a data-masked input inside `dplyr::transmute()` and checks it is numeric.
- And first of all, `foo::summarise_bmi()` takes two data-masked inputs inside `bar::summarise_stats()` and transforms them to a single BMI value.
There is a fourth context, the global environment where `summarise_bmi()` is called with two columns defined in a data frame, one of which is transformed on the fly with the user function `div100()`.
All of these contexts (except to some extent the global environment) contain functions that are private and invisible to foreign functions. Yet, the final expanded data-masked expression that is evaluated down the line looks like this (with caret characters indicating the quosure boundaries):
```r
dplyr::transmute(
var = ^check_numeric(^bmi(^mass, ^div100(height)))
)
```
The role of quosures is to let R know that `check_numeric()` should be found in the bar package, `bmi()` in the foo package, and `div100()` in the global environment.
# When should I create quosures?
As a tidyverse user you generally don't need to worry about quosures because `{{` and `...` will create them for you. Introductory texts like [Programming with dplyr](https://dplyr.tidyverse.org/articles/programming.html) or the [standard data-mask programming patterns][topic-data-mask-programming] don't even mention the term. In more complex cases you might need to create quosures with [enquo()] or [enquos()] (even though you generally don't need to know or care that these functions return quosures). In this section, we explore when quosures are necessary in these more advanced applications.
## Foreign and local expressions
As a rule of thumb, quosures are only needed for arguments defused with [enquo()] or [enquos()] (or with `r link("{{")` which calls `enquo()` implicitly):
```r
my_function <- function(var) {
var <- enquo(var)
their_function(!!var)
}
# Equivalently
my_function <- function(var) {
their_function({{ var }})
}
```
Wrapping defused arguments in quosures is needed because expressions supplied as argument comes from a different environment, the environment of your user. For local expressions created in your function, you generally don't need to create quosures:
```{r, comment = "#>", collapse = TRUE}
my_mean <- function(data, var) {
# `expr()` is sufficient, no need for `quo()`
expr <- expr(mean({{ var }}))
dplyr::summarise(data, !!expr)
}
my_mean(mtcars, cyl)
```
Using [quo()] instead of [expr()] would have worked too but it is superfluous because `dplyr::summarise()`, which uses [enquos()], is already in charge of wrapping your expression within a quosure scoped in your environment.
The same applies if you evaluate manually. By default, [eval()] and [eval_tidy()] capture your environment:
```{r, comment = "#>", collapse = TRUE}
my_mean <- function(data, var) {
expr <- expr(mean({{ var }}))
eval_tidy(expr, data)
}
my_mean(mtcars, cyl)
```
## External defusing
An exception to this rule of thumb (wrap foreign expressions in quosures, not your own expressions) arises when your function takes multiple expressions in a list instead of `...`. The preferred approach in that case is to take a tidy selection so that users can combine multiple columns using `c()`. If that is not possible, you can take a list of externally defused expressions:
```r
my_group_by <- function(data, vars) {
stopifnot(is_quosures(vars))
data %>% dplyr::group_by(!!!vars)
}
mtcars %>% my_group_by(dplyr::vars(cyl, am))
```
In this pattern, `dplyr::vars()` defuses expressions externally. It creates a list of quosures because the expressions are passed around from function to function like regular arguments. In fact, `dplyr::vars()` and `ggplot2::vars()` are simple aliases of [quos()].
```r
dplyr::vars(cyl, am)
#> >
#>
#> [[1]]
#>
#> expr: ^cyl
#> env: global
#>
#> [[2]]
#>
#> expr: ^am
#> env: global
```
For more information about external defusing, see `r link("topic_multiple_columns")`.
# Technical description of quosures
A quosure carries two things:
- An expression (get it with [quo_get_expr()]).
- An environment (get it with [quo_get_env()]).
And implements these behaviours:
- It is _callable_. Evaluation produces a result.
For historical reasons, [base::eval()] doesn't support quosure evaluation. Quosures currently require [eval_tidy()]. We would like to fix this limitation in the future.
- It is _hygienic_. It evaluates in the tracked environment.
- It is _maskable_. If evaluated in a data mask (currently only masks created with [eval_tidy()] or [new_data_mask()]), the mask comes first in scope before the quosure environment.
Conceptually, a quosure inherits from two chains of environments, the data mask and the user environment. In practice rlang implements this special scoping by rechaining the top of the data mask to the quosure environment currently under evaluation.
There are similarities between promises (the ones R uses to implement lazy evaluation, not the async expressions from the promises package) and quosures. One important difference is that promises are only evaluated once and cache the result for subsequent evaluation. Quosures behave more like calls and can be evaluated repeatedly, potentially in a different data mask. This property is useful to implement split-apply-combine evaluations.
# See also
- [enquo()] and [enquos()] to defuse function arguments as quosures. This is the main way quosures are created.
- [quo()] which is like [expr()] but wraps in a quosure. Usually it is not needed to wrap local expressions yourself.
- [quo_get_expr()] and [quo_get_env()] to access quosure components.
- [new_quosure()] and [as_quosure()] to assemble a quosure from components.
rlang/man/rmd/topic-condition-customisation.Rmd 0000644 0001762 0000144 00000006434 14175213516 021373 0 ustar ligges users ```{r, child = "setup.Rmd", include = FALSE}
```
Various aspects of the condition messages displayed by [abort()], [warn()], and [inform()] can be customised using options from the [cli](https://cli.r-lib.org) package.
# Turning off unicode bullets
By default, bulleted lists are prefixed with unicode symbols:
\ifelse{latex}{\emph{Not in PDF manual.}}{\if{html}{\out{
}}}
Set this option to use simple letters instead:
```r
options(cli.condition_unicode_bullets = FALSE)
rlang::abort(c(
"The error message.",
"*" = "Regular bullet.",
"i" = "Informative bullet.",
"x" = "Cross bullet.",
"v" = "Victory bullet.",
">" = "Arrow bullet."
))
#> Error:
#> ! The error message.
#> * Regular bullet.
#> i Informative bullet.
#> x Cross bullet.
#> v Victory bullet.
#> > Arrow bullet.
```
# Changing the bullet symbols
You can specify what symbol to use for each type of bullet through your cli user theme. For instance, here is how to uniformly use `*` for all bullet kinds:
```r
options(cli.user_theme = list(
".cli_rlang .bullet-*" = list(before = "* "),
".cli_rlang .bullet-i" = list(before = "* "),
".cli_rlang .bullet-x" = list(before = "* "),
".cli_rlang .bullet-v" = list(before = "* "),
".cli_rlang .bullet->" = list(before = "* ")
))
rlang::abort(c(
"The error message.",
"*" = "Regular bullet.",
"i" = "Informative bullet.",
"x" = "Cross bullet.",
"v" = "Victory bullet.",
">" = "Arrow bullet."
))
#> Error:
#> ! The error message.
#> * Regular bullet.
#> * Informative bullet.
#> * Cross bullet.
#> * Victory bullet.
#> * Arrow bullet.
```
If you want all the bullets to be the same, including the leading bullet, you can achieve this using the `bullet` class:
```r
options(cli.user_theme = list(
".cli_rlang .bullet" = list(before = "* ")
))
rlang::abort(c(
"The error message.",
"*" = "Regular bullet.",
"i" = "Informative bullet.",
"x" = "Cross bullet.",
"v" = "Victory bullet.",
">" = "Arrow bullet."
))
#> Error:
#> * The error message.
#> * Regular bullet.
#> * Informative bullet.
#> * Cross bullet.
#> * Victory bullet.
#> * Arrow bullet.
```
# Changing the foreground and background colour of error calls
When called inside a function, `abort()` displays the function call to help contextualise the error:
```{r, error = TRUE}
splash <- function() {
abort("Can't splash without water.")
}
splash()
```
The call is formatted with cli as a `code` element. This is not visible in the manual, but code text is formatted with a highlighted background colour by default. When this can be reliably detected, that background colour is different depending on whether you're using a light or dark theme.
You can override the colour of code elements in your cli theme. Here is my personal configuration that fits well with the colour theme I currently use in my IDE:
```r
options(cli.user_theme = list(
span.code = list(
"background-color" = "#3B4252",
color = "#E5E9F0"
)
))
```
rlang/man/rmd/topic-data-mask-ambiguity.Rmd 0000644 0001762 0000144 00000016011 14175213516 020330 0 ustar ligges users ```{r, child = "setup.Rmd", include = FALSE}
```
[Data masking][topic-data-mask] is an R feature that blends programming variables that live inside environments (env-variables) with statistical variables stored in data frames (data-variables). This mixture makes it easy to refer to data frame columns as well as objects defined in the current environment.
```{r, comment = "#>", collapse = TRUE}
x <- 100
mtcars %>% dplyr::summarise(mean(disp / x))
```
However this convenience introduces an ambiguity between data-variables and env-variables which might cause __collisions__.
## Column collisions
In the following snippet, are we referring to the env-variable `x` or to the data-variable of the same name?
```{r, comment = "#>", collapse = TRUE}
df <- data.frame(x = NA, y = 2)
x <- 100
df %>% dplyr::mutate(y = y / x)
```
A column collision occurs when you want to use an object defined outside of the data frame, but a column of the same name happens to exist.
## Object collisions
The opposite problem occurs when there is a typo in a data-variable name and an env-variable of the same name exists:
```{r, comment = "#>", collapse = TRUE}
df <- data.frame(foo = "right")
ffo <- "wrong"
df %>% dplyr::mutate(foo = toupper(ffo))
```
Instead of a typo, it might also be that you were expecting a column in the data frame which is unexpectedly missing. In both cases, if a variable can't be found in the data mask, R looks for variables in the surrounding environment. This isn't what we intended here and it would have been better to fail early with a "Column not found" error.
## Preventing collisions
In casual scripts or interactive programming, data mask ambiguity is not a huge deal compared to the payoff of iterating quickly while developing your analysis. However in production code and in package functions, the ambiguity might cause collision bugs in the long run.
Fortunately it is easy to be explicit about the scoping of variables with a little more verbose code. This topic lists the solutions and workarounds that have been created to solve ambiguity issues in data masks.
### The `.data` and `.env` pronouns
The simplest solution is to use the [`.data`] and [`.env`] pronouns to disambiguate between data-variables and env-variables.
```{r, comment = "#>", collapse = TRUE}
df <- data.frame(x = 1, y = 2)
x <- 100
df %>% dplyr::mutate(y = .data$y / .env$x)
```
This is especially useful in functions because the data frame is not known in advance and potentially contain masking columns for any of the env-variables in scope in the function:
```{r, comment = "#>", collapse = TRUE}
my_rescale <- function(data, var, factor = 10) {
data %>% dplyr::mutate("{{ var }}" := {{ var }} / factor)
}
# This works
data.frame(value = 1) %>% my_rescale(value)
# Oh no!
data.frame(factor = 0, value = 1) %>% my_rescale(value)
```
Subsetting function arguments with `.env` ensures we never hit a masking column:
```{r, comment = "#>", collapse = TRUE}
my_rescale <- function(data, var, factor = 10) {
data %>% dplyr::mutate("{{ var }}" := {{ var }} / .env$factor)
}
# Yay!
data.frame(factor = 0, value = 1) %>% my_rescale(value)
```
### Subsetting `.data` with env-variables
The [`.data`] pronoun may be used as a name-to-data-mask pattern (see `r link("topic_data_mask_programming")`):
```{r, comment = "#>", collapse = TRUE}
var <- "cyl"
mtcars %>% dplyr::summarise(mean = mean(.data[[var]]))
```
In this example, the env-variable `var` is used inside the data mask to subset the `.data` pronoun. Does this mean that `var` is at risk of a column collision if the input data frame contains a column of the same name? Fortunately not:
```{r, comment = "#>", collapse = TRUE}
var <- "cyl"
mtcars2 <- mtcars
mtcars2$var <- "wrong"
mtcars2 %>% dplyr::summarise(mean = mean(.data[[var]]))
```
The evaluation of `.data[[var]]` is set up in such a way that there is no ambiguity. The `.data` pronoun can only be subsetted with env-variables, not data-variables. Technically, this is because `[[` behaves like an _injection operator_ when applied to `.data`. It is evaluated very early before the data mask is even created. See the `!!` section below.
### Injecting env-variables with `!!`
[Injection operators][topic-inject] such as [`!!`][injection-operator] have interesting properties regarding the ambiguity problem. They modify a piece of code early on by injecting objects or other expressions before any data-masking logic comes into play. If you inject the _value_ of a variable, it becomes inlined in the expression. R no longer needs to look up any variable to find the value.
Taking the earlier division example, let's use `!!` to inject the value of the env-variable `x` inside the division expression:
```{r, comment = "#>", collapse = TRUE}
df <- data.frame(x = NA, y = 2)
x <- 100
df %>% dplyr::mutate(y = y / !!x)
```
While injection solves issues of ambiguity, it is a bit heavy handed compared to using the [`.env`] pronoun. Big objects inlined in expressions might cause issues in unexpected places, for instance they might make the calls in a [traceback()] less readable.
## No ambiguity in tidy selections
[Tidy selection](https://tidyselect.r-lib.org/reference/language.html) is a dialect of R that optimises column selection in tidyverse packages. Examples of functions that use tidy selections are `dplyr::select()` and `tidyr::pivot_longer()`.
Unlike data masking, tidy selections do not suffer from ambiguity. The selection language is designed in such a way that evaluation of expressions is either scoped in the data mask only, or in the environment only. Take this example:
```r
mtcars %>% dplyr::select(gear:ncol(mtcars))
```
`gear` is a symbol supplied to a selection operator `:` and thus scoped in the data mask only. Any other kind of expression, such as `ncol(mtcars)`, is evaluated as normal R code outside of any data context. This is why there is no column collision here:
```{r, comment = "#>", collapse = TRUE}
data <- data.frame(x = 1, data = 1:3)
data %>% dplyr::select(data:ncol(data))
```
It is useful to introduce two new terms. Tidy selections distinguish data-expressions and env-expressions:
- `data` is a data-expression that refers to the data-variable.
- `ncol(data)` is an env-expression that refers to the env-variable.
To learn more about the difference between the two kinds of expressions, see the [technical description of the tidy selection syntax](https://tidyselect.r-lib.org/articles/syntax.html).
### Names pattern with `all_of()`
`all_of()` is often used in functions as a [programming pattern][topic-data-mask-programming] that connects column names to a data mask, similarly to the [`.data`] pronoun. A simple example is:
```r
my_group_by <- function(data, vars) {
data %>% dplyr::group_by(across(all_of(vars)))
}
```
If tidy selections were affected by the data mask ambiguity, this function would be at risk of a column collision. It would break as soon as the user supplies a data frame containing a `vars` column. However, `all_of()` is an env-expression that is evaluated outside of the data mask, so there is no possibility of collisions.
rlang/man/rmd/topic-double-evaluation.Rmd 0000644 0001762 0000144 00000005447 14175213516 020130 0 ustar ligges users ```{r, child = "setup.Rmd", include = FALSE}
```
One inherent risk to metaprogramming is to evaluate multiple times a piece of code that appears to be evaluated only once. Take this data-masking function which takes a single input and produces two summaries:
```{r, comment = "#>", collapse = TRUE}
summarise_stats <- function(data, var) {
data %>%
dplyr::summarise(
mean = mean({{ var }}),
sd = sd({{ var }})
)
}
summarise_stats(mtcars, cyl)
```
This function is perfectly fine if the user supplies simple column names. However, data-masked arguments may also include _computations_.
```{r, comment = "#>", collapse = TRUE}
summarise_stats(mtcars, cyl * 100)
```
Computations may be slow and may produce side effects. For these
reasons, they should only be performed as many times as they appear in the code (unless explicitly documented, e.g. once per group with grouped data frames). Let's try again with a more complex computation:
```{r, comment = "#>", collapse = TRUE}
times100 <- function(x) {
message("Takes a long time...")
Sys.sleep(0.1)
message("And causes side effects such as messages!")
x * 100
}
summarise_stats(mtcars, times100(cyl))
```
Because of the side effects and the long running time, it is clear that `summarise_stats()` evaluates its input twice. This is because we've injected a defused expression in two different places. The data-masked expression created down the line looks like this (with caret signs representing [quosure][topic-quosure] boundaries):
```r
dplyr::summarise(
mean = ^mean(^times100(cyl)),
sd = ^sd(^times100(cyl))
)
```
The `times100(cyl)` expression is evaluated twice, even though it only appears once in the code. We have a double evaluation bug.
One simple way to fix it is to assign the defused input to a constant. You can then refer to that constant in the remaining of the code.
```{r, comment = "#>", collapse = TRUE}
summarise_stats <- function(data, var) {
data %>%
dplyr::transmute(
var = {{ var }},
) %>%
dplyr::summarise(
mean = mean(var),
sd = sd(var)
)
}
```
The defused input is now evaluated only once because it is injected only once:
```{r, comment = "#>", collapse = TRUE}
summarise_stats(mtcars, times100(cyl))
```
# What about glue strings?
`{{` [embracing in glue strings][glue-operators] doesn't suffer from the double evaluation problem:
```{r, comment = "#>", collapse = TRUE}
summarise_stats <- function(data, var) {
data %>%
dplyr::transmute(
var = {{ var }},
) %>%
dplyr::summarise(
"mean_{{ var }}" := mean(var),
"sd_{{ var }}" := sd(var)
)
}
summarise_stats(mtcars, times100(cyl))
```
Since a glue string doesn't need the result of an expression, only the original code converted (deparsed) to a string, it doesn't evaluate injected expressions.
rlang/man/rmd/topic-defuse.Rmd 0000644 0001762 0000144 00000015241 14175213516 015755 0 ustar ligges users ```{r, child = "setup.Rmd", include = FALSE}
```
When a piece of R code is defused, R doesn't return its value like it normally would. Instead it returns the expression in a special tree-like object that describes how to compute a value. These defused expressions can be thought of as blueprints or recipes for computing values.
Using [expr()] we can observe the difference between computing an expression and defusing it:
```{r, comment = "#>", collapse = TRUE}
# Return the result of `1 + 1`
1 + 1
# Return the expression `1 + 1`
expr(1 + 1)
```
Evaluation of a defused expression can be resumed at any time with [eval()] (see also [eval_tidy()]).
```{r, comment = "#>", collapse = TRUE}
# Return the expression `1 + 1`
e <- expr(1 + 1)
# Return the result of `1 + 1`
eval(e)
```
The most common use case for defusing expressions is to resume its evaluation in a [data mask][topic-data-mask]. This makes it possible for the expression to refer to columns of a data frame as if they were regular objects.
```{r, comment = "#>", collapse = TRUE}
e <- expr(mean(cyl))
eval(e, mtcars)
```
# Do I need to know about defused expressions?
As a tidyverse user you will rarely need to defuse expressions manually with `expr()`, and even more rarely need to resume evaluation with [eval()] or [eval_tidy()]. Instead, you call [data-masking][topic-data-mask] functions which take care of defusing your arguments and resuming them in the context of a data mask.
```{r, comment = "#>", collapse = TRUE}
mtcars %>% dplyr::summarise(
mean(cyl) # This is defused and data-masked
)
```
It is important to know that a function defuses its arguments because it requires slightly different methods when called from a function. The main thing is that arguments must be transported with the [embrace operator][embrace-operator] `{{`. It allows the data-masking function to defuse the correct expression.
```{r, comment = "#>", collapse = TRUE}
my_mean <- function(data, var) {
dplyr::summarise(data, mean = mean({{ var }}))
}
```
Read more about this in:
- `r link("topic_data_mask")`
- `r link("topic_data_mask_programming")`
# The booby trap analogy
The term "defusing" comes from an analogy to the evaluation model in R. As you may know, R uses lazy evaluation, which means that arguments are only evaluated when they are needed for a computation. Let's take two functions, `ignore()` which doesn't do anything with its argument, and `force()` which returns it:
```{r, comment = "#>", collapse = TRUE}
ignore <- function(arg) NULL
force <- function(arg) arg
ignore(warning("boom"))
force(warning("boom"))
```
A warning is only emitted when the function actually _triggers_ evaluation of its argument. Evaluation of arguments can be chained by passing them to other functions. If one of the functions ignores its argument, it breaks the chain of evaluation.
```{r, comment = "#>", collapse = TRUE}
f <- function(x) g(x)
g <- function(y) h(y)
h <- function(z) ignore(z)
f(warning("boom"))
```
In a way, arguments are like _booby traps_ which explode (evaluate) when touched. Defusing an argument can be seen as defusing the booby trap.
```{r, comment = "#>", collapse = TRUE}
expr(force(warning("boom")))
```
# Types of defused expressions
* __Calls__, like `f(1, 2, 3)` or `1 + 1` represent the action of calling a function to compute a new value, such as a vector.
* __Symbols__, like `x` or `df`, represent named objects. When the object pointed to by the symbol was defined in a function or in the global environment, we call it an environment-variable. When the object is a column in a data frame, we call it a data-variable.
* __Constants__, like `1` or `NULL`.
You can create new call or symbol objects by using the defusing function `expr()`:
```r
# Create a symbol representing objects called `foo`
expr(foo)
#> foo
# Create a call representing the computation of the mean of `foo`
expr(mean(foo, na.rm = TRUE))
#> mean(foo, na.rm = TRUE)
# Return a constant
expr(1)
#> [1] 1
expr(NULL)
#> NULL
```
Defusing is not the only way to create defused expressions. You can also assemble them from data:
```r
# Assemble a symbol from a string
var <- "foo"
sym(var)
# Assemble a call from strings, symbols, and constants
call("mean", sym(var), na.rm = TRUE)
```
# Local expressions versus function arguments
There are two main ways to defuse expressions, to which correspond two functions in rlang, [expr()] and [enquo()]:
* You can defuse your _own_ R expressions with `expr()`.
* You can defuse the expressions supplied by _the user_ of your function with the `en`-prefixed operators, such as `enquo()` and `enquos()`. These operators defuse function arguments.
# Defuse and inject
One purpose for defusing evaluation of an expression is to interface with [data-masking][topic-data-mask] functions by injecting the expression back into another function with `!!`. This is the [defuse-and-inject pattern][topic-metaprogramming].
```r
my_summarise <- function(data, arg) {
# Defuse the user expression in `arg`
arg <- enquo(arg)
# Inject the expression contained in `arg`
# inside a `summarise()` argument
data |> dplyr::summarise(mean = mean(!!arg, na.rm = TRUE))
}
```
Defuse-and-inject is usually performed in a single step with the embrace operator `r link("{{")`.
```r
my_summarise <- function(data, arg) {
# Defuse and inject in a single step with the embracing operator
data |> dplyr::summarise(mean = mean({{ arg }}, na.rm = TRUE))
}
```
Using `enquo()` and `!!` separately is useful in more complex cases where you need access to the defused expression instead of just passing it on.
# Defused arguments and quosures
If you inspect the return values of `expr()` and `enquo()`, you'll notice that the latter doesn't return a raw expression like the former. Instead it returns a [quosure], a wrapper containing an expression and an environment.
```r
expr(1 + 1)
#> 1 + 1
my_function <- function(arg) enquo(arg)
my_function(1 + 1)
#>
#> expr: ^1 + 1
#> env: global
```
R needs information about the environment to properly evaluate argument expressions because they come from a different context than the current function. For instance when a function in your package calls `dplyr::mutate()`, the quosure environment indicates where all the private functions of your package are defined.
Read more about the role of quosures in `r link("topic_quosure")`.
# Comparison with base R
Defusing is known as _quoting_ in other frameworks.
- The equivalent of `expr()` is [base::bquote()].
- The equivalent of `enquo()` is [base::substitute()]. The latter returns a naked expression instead of a quosure.
- There is no equivalent for `enquos(...)` but you can defuse dots as a list of naked expressions with `eval(substitute(alist(...)))`.
rlang/man/rmd/topic-data-mask.Rmd 0000644 0001762 0000144 00000015615 14175213516 016351 0 ustar ligges users ```{r, child = "setup.Rmd", include = FALSE}
```
Data-masking is a distinctive feature of R whereby programming is performed directly on a data set, with columns defined as normal objects.
```{r, comment = "#>", collapse = TRUE, error = TRUE}
# Unmasked programming
mean(mtcars$cyl + mtcars$am)
# Referring to columns is an error - Where is the data?
mean(cyl + am)
# Data-masking
with(mtcars, mean(cyl + am))
```
While data-masking makes it easy to program interactively with data frames, it makes it harder to create functions. Passing data-masked arguments to functions requires injection with the embracing operator `r link("{{")` or, in more complex cases, the injection operator [`!!`].
# Why does data-masking require embracing and injection?
Injection (also known as quasiquotation) is a metaprogramming feature that allows you to modify parts of a program. This is needed because under the hood data-masking works by [defusing][topic-defuse] R code to prevent its immediate evaluation. The defused code is resumed later on in a context where data frame columns are defined.
Let's see what happens when we pass arguments to a data-masking function like `summarise()` in the normal way:
```{r, comment = "#>", collapse = TRUE, error = TRUE}
my_mean <- function(data, var1, var2) {
dplyr::summarise(data, mean(var1 + var2))
}
my_mean(mtcars, cyl, am)
```
The problem here is that `summarise()` defuses the R code it was supplied, i.e. `mean(var1 + var2)`. Instead we want it to see `mean(cyl + am)`. This is why we need injection, we need to modify that piece of code by injecting the code supplied to the function in place of `var1` and `var2`.
To inject a function argument in data-masked context, just embrace it with `{{`:
```{r, comment = "#>", collapse = TRUE}
my_mean <- function(data, var1, var2) {
dplyr::summarise(data, mean({{ var1 }} + {{ var2 }}))
}
my_mean(mtcars, cyl, am)
```
See `r link("topic_data_mask_programming")` to learn more about creating functions around data-masking functions.
# What does "masking" mean?
In normal R programming objects are defined in the current environment, for instance in the global environment or the environment of a function.
```{r, comment = "#>", collapse = TRUE}
factor <- 1000
# Can now use `factor` in computations
mean(mtcars$cyl * factor)
```
This environment also contains all functions currently in scope. In a script this includes the functions attached with `library()` calls; in a package, the functions imported from other packages. If evaluation was performed only in the data frame, we'd lose track of these objects and functions necessary to perform computations.
To keep these objects and functions in scope, the data frame is inserted at the bottom of the current chain of environments. It comes first and has precedence over the user environment. In other words, it _masks_ the user environment.
Since masking blends the data and the user environment by giving priority to the former, R can sometimes use a data frame column when you really intended to use a local object.
```{r, comment = "#>", collapse = TRUE}
# Defining an env-variable
cyl <- 1000
# Referring to a data-variable
dplyr::summarise(mtcars, mean(cyl))
```
The tidy eval framework provides [pronouns][.data] to help disambiguate between the mask and user contexts. It is often a good idea to use these pronouns in production code.
```{r, comment = "#>", collapse = TRUE}
cyl <- 1000
mtcars %>%
dplyr::summarise(
mean_data = mean(.data$cyl),
mean_env = mean(.env$cyl)
)
```
Read more about this in `r link("topic_data_mask_ambiguity")`.
# How does data-masking work?
Data-masking relies on three language features:
- [Argument defusal][topic-defuse] with [substitute()] (base R) or [enquo()], [enquos()], and `r link("{{")` (rlang). R code is defused so it can be evaluated later on in a special environment enriched with data.
- First class environments. Environments are a special type of list-like object in which defused R code can be evaluated. The named elements in an environment define objects. Lists and data frames can be transformed to environments:
```r
as.environment(mtcars)
#>
```
- Explicit evaluation with [eval()] (base) or [eval_tidy()] (rlang). When R code is defused, evaluation is interrupted. It can be resumed later on with [eval()]:
```{r, comment = "#>", collapse = TRUE}
expr(1 + 1)
eval(expr(1 + 1))
```
By default `eval()` and `eval_tidy()` evaluate in the current environment.
```{r, comment = "#>", collapse = TRUE, error = TRUE}
code <- expr(mean(cyl + am))
eval(code)
```
You can supply an optional list or data frame that will be converted to an environment.
```{r, comment = "#>", collapse = TRUE}
eval(code, mtcars)
```
Evaluation of defused code then occurs in the context of a data mask.
# History
The tidyverse embraced the data-masking approach in packages like ggplot2 and dplyr and eventually developed its own programming framework in the rlang package. None of this would have been possible without the following landmark developments from S and R authors.
- The S language introduced data scopes with [attach()] (Becker, Chambers and Wilks, The New S Language, 1988).
- The S language introduced data-masked formulas in modelling functions (Chambers and Hastie, 1993).
- Peter Dalgaard (R team) wrote the frametools package in 1997. It was later included in R as [base::transform()] and [base::subset()]. This API is an important source of inspiration for the dplyr package. It was also the first apparition of _selections_, a variant of data-masking extended and codified later on in the [tidyselect package](https://tidyselect.r-lib.org/articles/syntax.html).
- In 2000 Luke Tierney (R team) [changed formulas](https://github.com/wch/r-source/commit/a945ac8e) to keep track of their original environments. This change published in R 1.1.0 was a crucial step towards hygienic data masking, i.e. the proper resolution of symbols in their original environments. Quosures were inspired by the environment-tracking mechanism of formulas.
- Luke introduced [base::with()] in 2001.
- In 2006 the [data.table package](https://r-datatable.com) included data-masking and selections in the `i` and `j` arguments of the `[` method of a data frame.
- The [dplyr package](https://dplyr.tidyverse.org/) was published in 2014.
- The rlang package developed tidy eval in 2017 as the data-masking framework of the tidyverse. It introduced the notions of [quosure][topic-quosure], [implicit injection][topic-inject] with `!!` and `!!!`, and [data pronouns][.data].
- In 2019, injection with `{{` was introduced in [rlang 0.4.0](https://www.tidyverse.org/blog/2019/06/rlang-0-4-0/) to simplify the defuse-and-inject pattern. This operator allows R programmers to transport data-masked arguments across functions more intuitively and with minimal boilerplate.
# See also
* `r link("topic_data_mask_programming")`
* `r link("topic_defuse")`
rlang/man/rmd/topic-condition-formatting.Rmd 0000644 0001762 0000144 00000003777 14175213516 020653 0 ustar ligges users ```{r, child = "setup.Rmd", include = FALSE}
```
Condition signallers like [abort()], [warn()], and [signal()] take a character vector of __bulleted text__ as `message` argument. This makes it easy to write messages in a list format where each bullet conveys a single important point.
```{r, error = TRUE}
abort(c(
"The error header",
"*" = "An error bullet",
"i" = "An info bullet",
"x" = "A cross bullet"
))
```
See the [tidyverse error style guide](https://style.tidyverse.org/error-messages.html) for more about this style of error messaging.
By default, condition messages use unicode symbols rather than simple letters. This is not the case here because unicode isn't supported in documentation. If you'd like to disable unicode symbols globally, add this to your Rprofile:
```r
options(cli.condition_unicode_bullets = FALSE)
```
## Use cli formatting
By default, rlang uses an internal mechanism to format bullets. It is preferable to delegate formatting to the [cli package](https://cli.r-lib.org/) because it uses sophisticated paragraph wrapping and bullet indenting that make long lines easier to read. In the following example, a long `!` bullet is broken with an indented newline:
```r
rlang::global_entrace(class = "errorr")
#> Error in `rlang::global_entrace()`:
#> ! `class` must be one of "error", "warning", or "message",
#> not "errorr".
#> i Did you mean "error"?
```
To enable cli formatting, use [cli::cli_abort()], [cli::cli_warn()], and [cli::cli_inform()]. Not only do these wrappers improve the formatting of messages, they also add many features such as interpolation, semantic formatting of text elements, and pluralisation:
```r
inform_marbles <- function(n_marbles) {
cli::cli_inform(c(
"i" = "I have {n_marbles} shiny marble{?s} in my bag.",
"v" = "Way to go {.code cli::cli_inform()}!"
))
}
inform_marbles(1)
#> i I have 1 shiny marble in my bag.
#> v Way to go `cli::cli_inform()`!
inform_marbles(2)
#> i I have 2 shiny marbles in my bag.
#> v Way to go `cli::cli_inform()`!
```
rlang/man/rmd/topic-inject-out-of-context.Rmd 0000644 0001762 0000144 00000005506 14175213516 020652 0 ustar ligges users ```{r, child = "setup.Rmd", include = FALSE}
```
The [injection operators][topic-inject] `r link("{{")`, [`!!`][injection-operator], and [`!!!`][splice-operator] are an extension of the R syntax developed for tidyverse packages. Because they are not part of base R, they suffer from some limitations. In particular no specific error is thrown when they are used in unexpected places.
## Using `{{` out of context
The embrace operator `r link("{{")` is a feature available in [data-masked][topic-data-mask] arguments powered by tidy eval. If you use it elsewhere, it is interpreted as a double `{` wrapping.
In the R language, `{` is like `(` but takes multiple expressions instead of one:
```{r, comment = "#>", collapse = TRUE}
{
1 # Discarded
2
}
list(
{ message("foo"); 2 }
)
```
Just like you can wrap an expression in as many parentheses as you'd like, you can wrap multiple times with braces:
```{r, comment = "#>", collapse = TRUE}
((1))
{{ 2 }}
```
So nothing prevents you from embracing a function argument in a context where this operation is not implemented. R will just treat the braces like a set of parentheses and silently return the result:
```{r, comment = "#>", collapse = TRUE}
f <- function(arg) list({{ arg }})
f(1)
```
This sort of no-effect embracing should be avoided in real code because it falsely suggests that the function supports the tidy eval operator and that something special is happening.
However in many cases embracing is done to implement [data masking][topic-data-mask]. It is likely that the function will be called with data-variables references which R won't be able to resolve properly:
```{r, comment = "#>", collapse = TRUE, error = TRUE}
my_mean <- function(data, var) {
with(data, mean({{ var }}))
}
my_mean(mtcars, cyl)
```
Since [with()] is a base data-masking function that doesn't support tidy eval operators, the embrace operator does not work and we get an object not found error.
## Using `!!` and `!!!` out of context
The injection operators [`!!`] and [`!!!`] are implemented in [data-masked][topic-data-mask] arguments, [dynamic dots][dyn-dots], and within [inject()]. When used in other contexts, they are interpreted by R as double and triple _negations_.
Double negation can be used in ordinary code to convert an input to logical:
```{r, comment = "#>", collapse = TRUE}
!!10
!!0
```
Triple negation is essentially the same as simple negation:
```{r, comment = "#>", collapse = TRUE}
!10
!!!10
```
This means that when injection operators are used in the wrong place, they will be interpreted as negation. In the best case scenario you will get a type error:
```{r, comment = "#>", collapse = TRUE, error = TRUE}
!"foo"
!quote(foo)
!quote(foo())
```
In the worst case, R will silently convert the input to logical. Unfortunately there is no systematic way of checking for these errors.
rlang/man/rmd/setup.Rmd 0000644 0001762 0000144 00000000535 14175213516 014526 0 ustar ligges users ```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
library(rlang)
`%>%` <- magrittr::`%>%`
is_installed("dplyr")
# Better printing
mtcars <- tibble::as_tibble(mtcars)
iris <- tibble::as_tibble(iris)
options(
tibble.print_min = 4,
tibble.print_max = 4
)
# Fix Latex error
options(
cli.unicode = FALSE
)
```
rlang/man/check_dots_empty.Rd 0000644 0001762 0000144 00000003143 14175213516 015751 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dots-ellipsis.R
\name{check_dots_empty}
\alias{check_dots_empty}
\title{Check that dots are empty}
\usage{
check_dots_empty(
env = caller_env(),
error = NULL,
call = caller_env(),
action = abort
)
}
\arguments{
\item{env}{Environment in which to look for \code{...}.}
\item{error}{An optional error handler passed to \code{\link[=try_fetch]{try_fetch()}}. Use
this e.g. to demote an error into a warning.}
\item{call}{The execution environment of a currently
running function, e.g. \code{caller_env()}. The function will be
mentioned in error messages as the source of the error. See the
\code{call} argument of \code{\link[=abort]{abort()}} for more information.}
\item{action}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}}
}
\description{
\code{...} can be inserted in a function signature to force users to
fully name the details arguments. In this case, supplying data in
\code{...} is almost always a programming error. This function checks
that \code{...} is empty and fails otherwise.
}
\details{
In packages, document \code{...} with this standard tag:\preformatted{ @inheritParams rlang::args_dots_empty
}
}
\examples{
f <- function(x, ..., foofy = 8) {
check_dots_empty()
x + foofy
}
# This fails because `foofy` can't be matched positionally
try(f(1, 4))
# This fails because `foofy` can't be matched partially by name
try(f(1, foof = 4))
# Thanks to `...`, it must be matched exactly
f(1, foofy = 4)
}
rlang/man/rep_along.Rd 0000644 0001762 0000144 00000001563 14127057575 014407 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vec-new.R
\name{rep_along}
\alias{rep_along}
\alias{rep_named}
\title{Create vectors matching the length of a given vector}
\usage{
rep_along(along, x)
rep_named(names, x)
}
\arguments{
\item{along}{Vector whose length determine how many times \code{x}
is repeated.}
\item{x}{Values to repeat.}
\item{names}{Names for the new vector. The length of \code{names}
determines how many times \code{x} is repeated.}
}
\description{
These functions take the idea of \code{\link[=seq_along]{seq_along()}} and apply it to
repeating values.
}
\examples{
x <- 0:5
rep_along(x, 1:2)
rep_along(x, 1)
# Create fresh vectors by repeating missing values:
rep_along(x, na_int)
rep_along(x, na_chr)
# rep_named() repeats a value along a names vectors
rep_named(c("foo", "bar"), list(letters))
}
\seealso{
new-vector
}
rlang/man/set_attrs.Rd 0000644 0001762 0000144 00000001134 14175213516 014433 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{set_attrs}
\alias{set_attrs}
\title{Add attributes to an object}
\usage{
set_attrs(.x, ...)
}
\arguments{
\item{.x, ...}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
}
\keyword{internal}
rlang/man/check_dots_empty0.Rd 0000644 0001762 0000144 00000001234 14175213516 016030 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dots-ellipsis.R
\name{check_dots_empty0}
\alias{check_dots_empty0}
\title{Check that dots are empty (low level variant)}
\usage{
check_dots_empty0(..., call = caller_env())
}
\arguments{
\item{...}{Dots which should be empty.}
}
\description{
\code{check_dots_empty0()} is a more efficient version of
\code{\link[=check_dots_empty]{check_dots_empty()}} with a slightly different interface. Instead
of inspecting the current environment for dots, it directly takes
\code{...}. It is only meant for very low level functions where a
couple microseconds make a difference.
}
\keyword{internal}
rlang/man/topic-quosure.Rd 0000644 0001762 0000144 00000023223 14175213516 015245 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/topic-nse.R
\name{topic-quosure}
\alias{topic-quosure}
\title{What are quosures and when are they needed?}
\description{
A quosure is a special type of \link[=topic-defuse]{defused expression} that keeps track of the original context the expression was written in. The tracking capabilities of quosures is important when interfacing \link[=topic-data-mask]{data-masking} functions together because the functions might come from two unrelated environments, like two different packages.
}
\section{Blending environments}{
Let's take an example where the R user calls the function \code{summarise_bmi()} from the foo package to summarise a data frame with statistics of a BMI value. Because the \code{height} variable of their data frame is not in metres, they use a custom function \code{div100()} to rescale the column.\if{html}{\out{
}}\preformatted{# Global environment of user
div100 <- function(x) \{
x / 100
\}
dplyr::starwars \%>\%
foo::summarise_bmi(mass, div100(height))
}\if{html}{\out{
}}
The \code{summarise_bmi()} function is a data-masking function defined in the namespace of the foo package which looks like this:\if{html}{\out{
}}\preformatted{# Namespace of package foo
bmi <- function(mass, height) \{
mass / height^2
\}
summarise_bmi <- function(data, mass, height) \{
data \%>\%
bar::summarise_stats(bmi(\{\{ mass \}\}, \{\{ height \}\}))
\}
}\if{html}{\out{
}}
The foo package uses the custom function \code{bmi()} to perform a computation on two vectors. It interfaces with \code{summarise_stats()} defined in bar, another package whose namespace looks like this:\if{html}{\out{
}}\preformatted{# Namespace of package bar
check_numeric <- function(x) \{
stopifnot(is.numeric(x))
x
\}
summarise_stats <- function(data, var) \{
data \%>\%
dplyr::transmute(
var = check_numeric(\{\{ var \}\})
) \%>\%
dplyr::summarise(
mean = mean(var, na.rm = TRUE),
sd = sd(var, na.rm = TRUE)
)
\}
}\if{html}{\out{
}}
Again the package bar uses a custom function, \code{check_numeric()}, to validate its input. It also interfaces with data-masking functions from dplyr (using the \link[=topic-double-evaluation]{define-a-constant} trick to avoid issues of double evaluation).
There are three data-masking functions simultaneously interfacing in this snippet:
\itemize{
\item At the bottom, \code{dplyr::transmute()} takes a data-masked input, and creates a data frame of a single column named \code{var}.
\item Before this, \code{bar::summarise_stats()} takes a data-masked input inside \code{dplyr::transmute()} and checks it is numeric.
\item And first of all, \code{foo::summarise_bmi()} takes two data-masked inputs inside \code{bar::summarise_stats()} and transforms them to a single BMI value.
}
There is a fourth context, the global environment where \code{summarise_bmi()} is called with two columns defined in a data frame, one of which is transformed on the fly with the user function \code{div100()}.
All of these contexts (except to some extent the global environment) contain functions that are private and invisible to foreign functions. Yet, the final expanded data-masked expression that is evaluated down the line looks like this (with caret characters indicating the quosure boundaries):\if{html}{\out{
}}\preformatted{dplyr::transmute(
var = ^check_numeric(^bmi(^mass, ^div100(height)))
)
}\if{html}{\out{
}}
The role of quosures is to let R know that \code{check_numeric()} should be found in the bar package, \code{bmi()} in the foo package, and \code{div100()} in the global environment.
}
\section{When should I create quosures?}{
As a tidyverse user you generally don't need to worry about quosures because \verb{\{\{} and \code{...} will create them for you. Introductory texts like \href{https://dplyr.tidyverse.org/articles/programming.html}{Programming with dplyr} or the \link[=topic-data-mask-programming]{standard data-mask programming patterns} don't even mention the term. In more complex cases you might need to create quosures with \code{\link[=enquo]{enquo()}} or \code{\link[=enquos]{enquos()}} (even though you generally don't need to know or care that these functions return quosures). In this section, we explore when quosures are necessary in these more advanced applications.
\subsection{Foreign and local expressions}{
As a rule of thumb, quosures are only needed for arguments defused with \code{\link[=enquo]{enquo()}} or \code{\link[=enquos]{enquos()}} (or with \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}} which calls \code{enquo()} implicitly):\if{html}{\out{
}}\preformatted{my_function <- function(var) \{
var <- enquo(var)
their_function(!!var)
\}
# Equivalently
my_function <- function(var) \{
their_function(\{\{ var \}\})
\}
}\if{html}{\out{
}}
Wrapping defused arguments in quosures is needed because expressions supplied as argument comes from a different environment, the environment of your user. For local expressions created in your function, you generally don't need to create quosures:\if{html}{\out{
}}\preformatted{my_mean <- function(data, var) \{
# `expr()` is sufficient, no need for `quo()`
expr <- expr(mean(\{\{ var \}\}))
dplyr::summarise(data, !!expr)
\}
my_mean(mtcars, cyl)
#> # A tibble: 1 x 1
#> `mean(cyl)`
#>
#> 1 6.19
}\if{html}{\out{
}}
Using \code{\link[=quo]{quo()}} instead of \code{\link[=expr]{expr()}} would have worked too but it is superfluous because \code{dplyr::summarise()}, which uses \code{\link[=enquos]{enquos()}}, is already in charge of wrapping your expression within a quosure scoped in your environment.
The same applies if you evaluate manually. By default, \code{\link[=eval]{eval()}} and \code{\link[=eval_tidy]{eval_tidy()}} capture your environment:\if{html}{\out{
}}
}
\subsection{External defusing}{
An exception to this rule of thumb (wrap foreign expressions in quosures, not your own expressions) arises when your function takes multiple expressions in a list instead of \code{...}. The preferred approach in that case is to take a tidy selection so that users can combine multiple columns using \code{c()}. If that is not possible, you can take a list of externally defused expressions:\if{html}{\out{
}}
In this pattern, \code{dplyr::vars()} defuses expressions externally. It creates a list of quosures because the expressions are passed around from function to function like regular arguments. In fact, \code{dplyr::vars()} and \code{ggplot2::vars()} are simple aliases of \code{\link[=quos]{quos()}}.\if{html}{\out{
}}
For more information about external defusing, see \ifelse{html}{\link[=topic-multiple-columns]{Taking multiple columns without ...}}{\link[=topic-multiple-columns]{Taking multiple columns without ...}}.
}
}
\section{Technical description of quosures}{
A quosure carries two things:
\itemize{
\item An expression (get it with \code{\link[=quo_get_expr]{quo_get_expr()}}).
\item An environment (get it with \code{\link[=quo_get_env]{quo_get_env()}}).
}
And implements these behaviours:
\itemize{
\item It is \emph{callable}. Evaluation produces a result.
For historical reasons, \code{\link[base:eval]{base::eval()}} doesn't support quosure evaluation. Quosures currently require \code{\link[=eval_tidy]{eval_tidy()}}. We would like to fix this limitation in the future.
\item It is \emph{hygienic}. It evaluates in the tracked environment.
\item It is \emph{maskable}. If evaluated in a data mask (currently only masks created with \code{\link[=eval_tidy]{eval_tidy()}} or \code{\link[=new_data_mask]{new_data_mask()}}), the mask comes first in scope before the quosure environment.
Conceptually, a quosure inherits from two chains of environments, the data mask and the user environment. In practice rlang implements this special scoping by rechaining the top of the data mask to the quosure environment currently under evaluation.
}
There are similarities between promises (the ones R uses to implement lazy evaluation, not the async expressions from the promises package) and quosures. One important difference is that promises are only evaluated once and cache the result for subsequent evaluation. Quosures behave more like calls and can be evaluated repeatedly, potentially in a different data mask. This property is useful to implement split-apply-combine evaluations.
}
\section{See also}{
\itemize{
\item \code{\link[=enquo]{enquo()}} and \code{\link[=enquos]{enquos()}} to defuse function arguments as quosures. This is the main way quosures are created.
\item \code{\link[=quo]{quo()}} which is like \code{\link[=expr]{expr()}} but wraps in a quosure. Usually it is not needed to wrap local expressions yourself.
\item \code{\link[=quo_get_expr]{quo_get_expr()}} and \code{\link[=quo_get_env]{quo_get_env()}} to access quosure components.
\item \code{\link[=new_quosure]{new_quosure()}} and \code{\link[=as_quosure]{as_quosure()}} to assemble a quosure from components.
}
}
\keyword{internal}
rlang/man/is_reference.Rd 0000644 0001762 0000144 00000002542 14127057575 015070 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/types.R
\name{is_reference}
\alias{is_reference}
\title{Is an object referencing another?}
\usage{
is_reference(x, y)
}
\arguments{
\item{x, y}{R objects.}
}
\description{
There are typically two situations where two symbols may refer to
the same object.
\itemize{
\item R objects usually have copy-on-write semantics. This is an
optimisation that ensures that objects are only copied if
needed. When you copy a vector, no memory is actually copied
until you modify either the original object or the copy is
modified.
Note that the copy-on-write optimisation is an implementation
detail that is not guaranteed by the specification of the R
language.
\item Assigning an \link[=is_copyable]{uncopyable} object (like an
environment) creates a reference. These objects are never copied
even if you modify one of the references.
}
}
\examples{
# Reassigning an uncopyable object such as an environment creates a
# reference:
env <- env()
ref <- env
is_reference(ref, env)
# Due to copy-on-write optimisation, a copied vector can
# temporarily reference the original vector:
vec <- 1:10
copy <- vec
is_reference(copy, vec)
# Once you modify on of them, the copy is triggered in the
# background and the objects cease to reference each other:
vec[[1]] <- 100
is_reference(copy, vec)
}
\keyword{internal}
rlang/man/call_inspect.Rd 0000644 0001762 0000144 00000001220 14175213516 015057 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stack.R
\name{call_inspect}
\alias{call_inspect}
\title{Inspect a call}
\usage{
call_inspect(...)
}
\arguments{
\item{...}{Arguments to display in the returned call.}
}
\description{
This function is a wrapper around \code{\link[base:match.call]{base::match.call()}}. It returns
its own function call.
}
\examples{
# When you call it directly, it simply returns what you typed
call_inspect(foo(bar), "" \%>\% identity())
# Pass `call_inspect` to functionals like `lapply()` or `map()` to
# inspect the calls they create around the supplied function
lapply(1:3, call_inspect)
}
rlang/man/arg_match.Rd 0000644 0001762 0000144 00000004521 14175213516 014353 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/arg.R
\name{arg_match}
\alias{arg_match}
\alias{arg_match0}
\title{Match an argument to a character vector}
\usage{
arg_match(
arg,
values = NULL,
...,
multiple = FALSE,
error_arg = caller_arg(arg),
error_call = caller_env()
)
arg_match0(arg, values, arg_nm = caller_arg(arg), error_call = caller_env())
}
\arguments{
\item{arg}{A symbol referring to an argument accepting strings.}
\item{values}{A character vector of possible values that \code{arg} can take.}
\item{...}{These dots are for future extensions and must be empty.}
\item{multiple}{Whether \code{arg} may contain zero or several values.}
\item{error_arg}{An argument name as a string. This argument
will be mentioned in error messages as the input that is at the
origin of a problem.}
\item{error_call}{The execution environment of a currently
running function, e.g. \code{caller_env()}. The function will be
mentioned in error messages as the source of the error. See the
\code{call} argument of \code{\link[=abort]{abort()}} for more information.}
\item{arg_nm}{Same as \code{error_arg}.}
}
\value{
The string supplied to \code{arg}.
}
\description{
This is equivalent to \code{\link[base:match.arg]{base::match.arg()}} with a few differences:
\itemize{
\item Partial matches trigger an error.
\item Error messages are a bit more informative and obey the tidyverse
standards.
}
\code{arg_match()} derives the possible values from the
\link[=caller_fn]{caller function}.
\code{arg_match0()} is a bare-bones version if performance is at a premium.
It requires a string as \code{arg} and explicit character \code{values}.
For convenience, \code{arg} may also be a character vector containing
every element of \code{values}, possibly permuted.
In this case, the first element of \code{arg} is used.
}
\examples{
fn <- function(x = c("foo", "bar")) arg_match(x)
fn("bar")
# Throws an informative error for mismatches:
try(fn("b"))
try(fn("baz"))
# Use the bare-bones version with explicit values for speed:
arg_match0("bar", c("foo", "bar", "baz"))
# For convenience:
fn1 <- function(x = c("bar", "baz", "foo")) fn3(x)
fn2 <- function(x = c("baz", "bar", "foo")) fn3(x)
fn3 <- function(x) arg_match0(x, c("foo", "bar", "baz"))
fn1()
fn2("bar")
try(fn3("zoo"))
}
\seealso{
\code{\link[=check_required]{check_required()}}
}
rlang/man/is_dictionaryish.Rd 0000644 0001762 0000144 00000000535 14175213516 015773 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/attr.R
\name{is_dictionaryish}
\alias{is_dictionaryish}
\title{Is a vector uniquely named?}
\usage{
is_dictionaryish(x)
}
\arguments{
\item{x}{A vector.}
}
\description{
Like \code{\link[=is_named]{is_named()}} but also checks that names are unique.
}
\keyword{internal}
rlang/man/with_handlers.Rd 0000644 0001762 0000144 00000001534 14175213516 015262 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{with_handlers}
\alias{with_handlers}
\alias{calling}
\alias{exiting}
\title{Establish handlers on the stack}
\usage{
with_handlers(.expr, ...)
calling(handler)
exiting(handler)
}
\arguments{
\item{.expr, ..., handler}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
As of rlang 1.0.0, \code{with_handlers()} is deprecated. Use the base
functions or the experimental \code{\link[=try_fetch]{try_fetch()}} function instead.
}
\keyword{internal}
rlang/man/has_name.Rd 0000644 0001762 0000144 00000001514 14127057575 014210 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/attr.R
\name{has_name}
\alias{has_name}
\title{Does an object have an element with this name?}
\usage{
has_name(x, name)
}
\arguments{
\item{x}{A data frame or another named object}
\item{name}{Element name(s) to check}
}
\value{
A logical vector of the same length as \code{name}
}
\description{
This function returns a logical value that indicates if a data
frame or another named object contains an element with a specific
name. Note that \code{has_name()} only works with vectors. For instance,
environments need the specialised function \code{\link[=env_has]{env_has()}}.
}
\details{
Unnamed objects are treated as if all names are empty strings. \code{NA}
input gives \code{FALSE} as output.
}
\examples{
has_name(iris, "Species")
has_name(mtcars, "gears")
}
rlang/man/cnd_inherits.Rd 0000644 0001762 0000144 00000005675 14175213516 015112 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd.R
\name{cnd_inherits}
\alias{cnd_inherits}
\title{Does a condition or its ancestors inherit from a class?}
\usage{
cnd_inherits(cnd, class)
}
\arguments{
\item{cnd}{A condition to test.}
\item{class}{A class passed to \code{\link[=inherits]{inherits()}}.}
}
\description{
Like any R objects, errors captured with catchers like \code{\link[=tryCatch]{tryCatch()}}
have a \code{\link[=class]{class()}} which you can test with \code{\link[=inherits]{inherits()}}. However,
with chained errors, the class of a captured error might be
different than the error that was originally signalled. Use
\code{cnd_inherits()} to detect whether an error or any of its \emph{parent}
inherits from a class.
Whereas \code{inherits()} tells you whether an object is a particular
kind of error, \code{cnd_inherits()} answers the question whether an
object is a particular kind of error or has been caused by such an
error.
}
\section{Capture an error with \code{cnd_inherits()}}{
Error catchers like \code{\link[=tryCatch]{tryCatch()}} and \code{\link[=try_fetch]{try_fetch()}} can only match
the class of a condition, not the class of its parents. To match a
class across the ancestry of an error, you'll need a bit of
craftiness.
Ancestry matching can't be done with \code{tryCatch()} at all so you'll
need to switch to \code{\link[=withCallingHandlers]{withCallingHandlers()}}. Alternatively, you can
use the experimental rlang function \code{\link[=try_fetch]{try_fetch()}} which is able to
perform the roles of both \code{tryCatch()} and \code{withCallingHandlers()}.
\subsection{\code{withCallingHandlers()}}{
Unlike \code{tryCatch()}, \code{withCallingHandlers()} does not capture an
error. If you don't explicitly jump with an \emph{error} or a \emph{value}
throw, nothing happens.
Since we don't want to throw an error, we'll throw a value using
\code{\link[=callCC]{callCC()}}:\if{html}{\out{
}}
}
\subsection{\code{try_fetch()}}{
This pattern is easier with \code{\link[=try_fetch]{try_fetch()}}. Like
\code{withCallingHandlers()}, it doesn't capture a matching error right
away. Instead, it captures it only if the handler doesn't return a
\code{\link[=zap]{zap()}} value.\if{html}{\out{
}}
}
}
rlang/man/global_handle.Rd 0000644 0001762 0000144 00000001730 14175213516 015200 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-handlers.R
\name{global_handle}
\alias{global_handle}
\title{Register default global handlers}
\usage{
global_handle(entrace = TRUE, prompt_install = TRUE)
}
\arguments{
\item{entrace}{Passed as \code{enable} argument to \code{\link[=global_entrace]{global_entrace()}}.}
\item{prompt_install}{Passed as \code{enable} argument to
\code{\link[=global_prompt_install]{global_prompt_install()}}.}
}
\description{
\code{global_handle()} sets up a default configuration for error,
warning, and message handling. It calls:
\itemize{
\item \code{\link[=global_entrace]{global_entrace()}} to enable rlang errors and warnings globally.
\item \code{\link[=global_prompt_install]{global_prompt_install()}} to recover from \code{packageNotFoundError}s
with a user prompt to install the missing package. Note that at
the time of writing (R 4.1), there are only very limited
situations where this handler works.
}
}
rlang/man/topic-defuse.Rd 0000644 0001762 0000144 00000021167 14175213516 015022 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/topic-nse.R
\name{topic-defuse}
\alias{topic-defuse}
\alias{quotation}
\alias{nse-defuse}
\title{Defusing R expressions}
\description{
When a piece of R code is defused, R doesn't return its value like it normally would. Instead it returns the expression in a special tree-like object that describes how to compute a value. These defused expressions can be thought of as blueprints or recipes for computing values.
Using \code{\link[=expr]{expr()}} we can observe the difference between computing an expression and defusing it:\if{html}{\out{
}}\preformatted{# Return the result of `1 + 1`
1 + 1
#> [1] 2
# Return the expression `1 + 1`
expr(1 + 1)
#> 1 + 1
}\if{html}{\out{
}}
Evaluation of a defused expression can be resumed at any time with \code{\link[=eval]{eval()}} (see also \code{\link[=eval_tidy]{eval_tidy()}}).\if{html}{\out{
}}\preformatted{# Return the expression `1 + 1`
e <- expr(1 + 1)
# Return the result of `1 + 1`
eval(e)
#> [1] 2
}\if{html}{\out{
}}
The most common use case for defusing expressions is to resume its evaluation in a \link[=topic-data-mask]{data mask}. This makes it possible for the expression to refer to columns of a data frame as if they were regular objects.\if{html}{\out{
}}
}
\section{Do I need to know about defused expressions?}{
As a tidyverse user you will rarely need to defuse expressions manually with \code{expr()}, and even more rarely need to resume evaluation with \code{\link[=eval]{eval()}} or \code{\link[=eval_tidy]{eval_tidy()}}. Instead, you call \link[=topic-data-mask]{data-masking} functions which take care of defusing your arguments and resuming them in the context of a data mask.\if{html}{\out{
}}\preformatted{mtcars \%>\% dplyr::summarise(
mean(cyl) # This is defused and data-masked
)
#> # A tibble: 1 x 1
#> `mean(cyl)`
#>
#> 1 6.19
}\if{html}{\out{
}}
It is important to know that a function defuses its arguments because it requires slightly different methods when called from a function. The main thing is that arguments must be transported with the \link[=embrace-operator]{embrace operator} \verb{\{\{}. It allows the data-masking function to defuse the correct expression.\if{html}{\out{
}}\preformatted{my_mean <- function(data, var) \{
dplyr::summarise(data, mean = mean(\{\{ var \}\}))
\}
}\if{html}{\out{
}}
Read more about this in:
\itemize{
\item \ifelse{html}{\link[=topic-data-mask]{What is data-masking and why do I need \{\{?}}{\link[=topic-data-mask]{What is data-masking and why do I need curly-curly?}}
\item \ifelse{html}{\link[=topic-data-mask-programming]{Data mask programming patterns}}{\link[=topic-data-mask-programming]{Data mask programming patterns}}
}
}
\section{The booby trap analogy}{
The term "defusing" comes from an analogy to the evaluation model in R. As you may know, R uses lazy evaluation, which means that arguments are only evaluated when they are needed for a computation. Let's take two functions, \code{ignore()} which doesn't do anything with its argument, and \code{force()} which returns it:\if{html}{\out{
}}\preformatted{ignore <- function(arg) NULL
force <- function(arg) arg
ignore(warning("boom"))
#> NULL
force(warning("boom"))
#> Warning in force(warning("boom")): boom
}\if{html}{\out{
}}
A warning is only emitted when the function actually \emph{triggers} evaluation of its argument. Evaluation of arguments can be chained by passing them to other functions. If one of the functions ignores its argument, it breaks the chain of evaluation.\if{html}{\out{
}}\preformatted{f <- function(x) g(x)
g <- function(y) h(y)
h <- function(z) ignore(z)
f(warning("boom"))
#> NULL
}\if{html}{\out{
}}
In a way, arguments are like \emph{booby traps} which explode (evaluate) when touched. Defusing an argument can be seen as defusing the booby trap.\if{html}{\out{
}}
}
\section{Types of defused expressions}{
\itemize{
\item \strong{Calls}, like \code{f(1, 2, 3)} or \code{1 + 1} represent the action of calling a function to compute a new value, such as a vector.
\item \strong{Symbols}, like \code{x} or \code{df}, represent named objects. When the object pointed to by the symbol was defined in a function or in the global environment, we call it an environment-variable. When the object is a column in a data frame, we call it a data-variable.
\item \strong{Constants}, like \code{1} or \code{NULL}.
}
You can create new call or symbol objects by using the defusing function \code{expr()}:\if{html}{\out{
}}\preformatted{# Create a symbol representing objects called `foo`
expr(foo)
#> foo
# Create a call representing the computation of the mean of `foo`
expr(mean(foo, na.rm = TRUE))
#> mean(foo, na.rm = TRUE)
# Return a constant
expr(1)
#> [1] 1
expr(NULL)
#> NULL
}\if{html}{\out{
}}
Defusing is not the only way to create defused expressions. You can also assemble them from data:\if{html}{\out{
}}\preformatted{# Assemble a symbol from a string
var <- "foo"
sym(var)
# Assemble a call from strings, symbols, and constants
call("mean", sym(var), na.rm = TRUE)
}\if{html}{\out{
}}
}
\section{Local expressions versus function arguments}{
There are two main ways to defuse expressions, to which correspond two functions in rlang, \code{\link[=expr]{expr()}} and \code{\link[=enquo]{enquo()}}:
\itemize{
\item You can defuse your \emph{own} R expressions with \code{expr()}.
\item You can defuse the expressions supplied by \emph{the user} of your function with the \code{en}-prefixed operators, such as \code{enquo()} and \code{enquos()}. These operators defuse function arguments.
}
}
\section{Defuse and inject}{
One purpose for defusing evaluation of an expression is to interface with \link[=topic-data-mask]{data-masking} functions by injecting the expression back into another function with \verb{!!}. This is the \link[=topic-metaprogramming]{defuse-and-inject pattern}.\if{html}{\out{
}}\preformatted{my_summarise <- function(data, arg) \{
# Defuse the user expression in `arg`
arg <- enquo(arg)
# Inject the expression contained in `arg`
# inside a `summarise()` argument
data |> dplyr::summarise(mean = mean(!!arg, na.rm = TRUE))
\}
}\if{html}{\out{
}}
Defuse-and-inject is usually performed in a single step with the embrace operator \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}}.\if{html}{\out{
}}\preformatted{my_summarise <- function(data, arg) \{
# Defuse and inject in a single step with the embracing operator
data |> dplyr::summarise(mean = mean(\{\{ arg \}\}, na.rm = TRUE))
\}
}\if{html}{\out{
}}
Using \code{enquo()} and \verb{!!} separately is useful in more complex cases where you need access to the defused expression instead of just passing it on.
}
\section{Defused arguments and quosures}{
If you inspect the return values of \code{expr()} and \code{enquo()}, you'll notice that the latter doesn't return a raw expression like the former. Instead it returns a \link{quosure}, a wrapper containing an expression and an environment.\if{html}{\out{
}}
R needs information about the environment to properly evaluate argument expressions because they come from a different context than the current function. For instance when a function in your package calls \code{dplyr::mutate()}, the quosure environment indicates where all the private functions of your package are defined.
Read more about the role of quosures in \ifelse{html}{\link[=topic-quosure]{What are quosures and when are they needed?}}{\link[=topic-quosure]{What are quosures and when are they needed?}}.
}
\section{Comparison with base R}{
Defusing is known as \emph{quoting} in other frameworks.
\itemize{
\item The equivalent of \code{expr()} is \code{\link[base:bquote]{base::bquote()}}.
\item The equivalent of \code{enquo()} is \code{\link[base:substitute]{base::substitute()}}. The latter returns a naked expression instead of a quosure.
\item There is no equivalent for \code{enquos(...)} but you can defuse dots as a list of naked expressions with \code{eval(substitute(alist(...)))}.
}
}
\keyword{internal}
rlang/man/try_fetch.Rd 0000644 0001762 0000144 00000011276 14175213516 014422 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-handlers.R
\name{try_fetch}
\alias{try_fetch}
\title{Try an expression with condition handlers}
\usage{
try_fetch(expr, ...)
}
\arguments{
\item{expr}{An R expression.}
\item{...}{<\code{\link[=dyn-dots]{dynamic-dots}}> Named condition
handlers. The names specify the condition class for which a
handler will be called.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
\code{try_fetch()} establishes handlers for conditions of a given class
(\code{"error"}, \code{"warning"}, \code{"message"}, ...). Handlers are functions
that take a condition object as argument and are called when the
corresponding condition class has been signalled.
A condition handler can:
\itemize{
\item \strong{Recover from conditions} with a value. In this case the computation of
\code{expr} is aborted and the recovery value is returned from
\code{try_fetch()}. Error recovery is useful when you don't want
errors to abruptly interrupt your program but resume at the
catching site instead.\preformatted{# Recover with the value 0
try_fetch(1 + "", error = function(cnd) 0)
}
\item \strong{Rethrow conditions}, e.g. using \code{abort(msg, parent = cnd)}.
See the \code{parent} argument of \code{\link[=abort]{abort()}}. This is typically done to
add information to low-level errors about the high-level context
in which they occurred.\preformatted{try_fetch(1 + "", error = function(cnd) abort("Failed.", parent = cnd))
}
\item \strong{Inspect conditions}, for instance to log data about warnings
or errors. In this case, the handler must return the \code{\link[=zap]{zap()}}
sentinel to instruct \code{try_fetch()} to ignore (or zap) that
particular handler. The next matching handler is called if any,
and errors bubble up to the user if no handler remains.\preformatted{log <- NULL
try_fetch(1 + "", error = function(cnd) \{
log <<- cnd
zap()
\})
}
}
Whereas \code{tryCatch()} catches conditions (discarding any running
code along the way) and then calls the handler, \code{try_fetch()} first
calls the handler with the condition on top of the currently
running code (fetches it where it stands) and then catches the
return value . This is a subtle difference that has implications
for the debuggability of your functions. See the comparison with
\code{tryCatch()} section below.
}
\section{Stack overflows}{
A stack overflow occurs when a program keeps adding to itself until
the stack memory (whose size is very limited unlike heap memory) is
exhausted.\preformatted{# A function that calls itself indefinitely causes stack overflows
f <- function() f()
f()
#> Error: C stack usage 9525680 is too close to the limit
}
Because memory is very limited when these errors happen, it is not
possible to call the handlers on the existing program stack.
Instead, error conditions are first caught by \code{try_fetch()} and only
then error handlers are called. Catching the error interrupts the
program up to the \code{try_fetch()} context, which allows R to reclaim
stack memory.
The practical implication is that error handlers should never
assume that the whole call stack is preserved. For instance a
\code{\link[=trace_back]{trace_back()}} capture might miss frames.
Note that error handlers are only run for stack overflows on R >=
4.2 (unreleased at the time of writing). On older versions of R the
handlers are simply not run. This is because these errors do not
inherit from the class \code{stackOverflowError} before R 4.2. Consider
using \code{\link[=tryCatch]{tryCatch()}} instead with critical error handlers that need
to capture all errors on old versions of R.
}
\section{Comparison with \code{tryCatch()}}{
\code{try_fetch()} generalises \code{tryCatch()} and \code{withCallingHandlers()}
in a single function. It reproduces the behaviour of both calling
and exiting handlers depending the on the return value of the
handler. If the handler returns the \code{\link[=zap]{zap()}} sentinel, it is taken
as a calling handler that declines to recover from a condition.
Otherwise, it is taken as an exiting handler which returns a value
from the catching site.
The important difference between \code{tryCatch()} and \code{try_fetch()} is
that the program in \code{expr} is still fully running when an error
handler is called. Because the call stack is preserved, this makes
it possible to capture a full backtrace from within the handler,
e.g. when rethrowing the error with \code{abort(parent = cnd)}.
Technically, \code{try_fetch()} is more similar to (and implemented on
top of) \code{\link[base:conditions]{base::withCallingHandlers()}} than \verb{tryCatch().}
}
rlang/man/rlang_error.Rd 0000644 0001762 0000144 00000004051 14175213516 014740 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd.R
\name{rlang_error}
\alias{rlang_error}
\title{Errors of class \code{rlang_error}}
\description{
\code{\link[=abort]{abort()}} and \code{\link[=error_cnd]{error_cnd()}} create errors of class \code{"rlang_error"}.
The differences with base errors are:
\itemize{
\item Implementing \code{conditionMessage()} methods for subclasses of
\code{"rlang_error"} is undefined behaviour. Instead, implement the
\code{\link[=cnd_header]{cnd_header()}} method (and possibly \code{\link[=cnd_body]{cnd_body()}} and
\code{\link[=cnd_footer]{cnd_footer()}}). These methods return character vectors which are
assembled by rlang when needed: when
\code{\link[=conditionMessage]{conditionMessage.rlang_error()}} is called
(e.g. via \code{\link[=try]{try()}}), when the error is displayed through \code{\link[=print]{print()}}
or \code{\link[=format]{format()}}, and of course when the error is displayed to the
user by \code{\link[=abort]{abort()}}.
\item \code{\link[=cnd_header]{cnd_header()}}, \code{\link[=cnd_body]{cnd_body()}}, and \code{\link[=cnd_footer]{cnd_footer()}} methods can be
overridden by storing closures in the \code{header}, \code{body}, and
\code{footer} fields of the condition. This is useful to lazily
generate messages based on state captured in the closure
environment.
\item \ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}} The \code{use_cli_format}
condition field instructs whether to use cli (or rlang's fallback
method if cli is not installed) to format the error message at
print time.
In this case, the \code{message} field may be a character vector of
header and bullets. These are formatted at the last moment to
take the context into account (starting position on the screen
and indentation).
See \code{\link[=local_use_cli]{local_use_cli()}} for automatically setting this field in
errors thrown with \code{\link[=abort]{abort()}} within your package.
}
}
rlang/man/vec_poke_n.Rd 0000644 0001762 0000144 00000002273 14175213516 014540 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/vec.R
\name{vec_poke_n}
\alias{vec_poke_n}
\alias{vec_poke_range}
\title{Poke values into a vector}
\usage{
vec_poke_n(x, start, y, from = 1L, n = length(y))
vec_poke_range(x, start, y, from = 1L, to = length(y) - from + 1L)
}
\arguments{
\item{x}{The destination vector.}
\item{start}{The index indicating where to start modifying \code{x}.}
\item{y}{The source vector.}
\item{from}{The index indicating where to start copying from \code{y}.}
\item{n}{How many elements should be copied from \code{y} to \code{x}.}
\item{to}{The index indicating the end of the range to copy from \code{y}.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
These tools are for R experts only. They copy elements from \code{y}
into \code{x} by mutation. You should only do this if you own \code{x},
i.e. if you have created it or if you are certain that it doesn't
exist in any other context. Otherwise you might create unintended
side effects that have undefined consequences.
}
\keyword{internal}
rlang/man/new_function.Rd 0000644 0001762 0000144 00000003071 14175213516 015123 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fn.R
\name{new_function}
\alias{new_function}
\title{Create a function}
\usage{
new_function(args, body, env = caller_env())
}
\arguments{
\item{args}{A named list or pairlist of default arguments. Note
that if you want arguments that don't have defaults, you'll need
to use the special function \code{\link[=pairlist2]{pairlist2()}}. If you need quoted
defaults, use \code{\link[=exprs]{exprs()}}.}
\item{body}{A language object representing the code inside the
function. Usually this will be most easily generated with
\code{\link[base:substitute]{base::quote()}}}
\item{env}{The parent environment of the function, defaults to the
calling environment of \code{new_function()}}
}
\description{
This constructs a new function given its three components:
list of arguments, body code and parent environment.
}
\examples{
f <- function() letters
g <- new_function(NULL, quote(letters))
identical(f, g)
# Pass a list or pairlist of named arguments to create a function
# with parameters. The name becomes the parameter name and the
# argument the default value for this parameter:
new_function(list(x = 10), quote(x))
new_function(pairlist2(x = 10), quote(x))
# Use `exprs()` to create quoted defaults. Compare:
new_function(pairlist2(x = 5 + 5), quote(x))
new_function(exprs(x = 5 + 5), quote(x))
# Pass empty arguments to omit defaults. `list()` doesn't allow
# empty arguments but `pairlist2()` does:
new_function(pairlist2(x = , y = 5 + 5), quote(x + y))
new_function(exprs(x = , y = 5 + 5), quote(x + y))
}
rlang/man/entrace.Rd 0000644 0001762 0000144 00000005561 14175213516 014054 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-entrace.R
\name{entrace}
\alias{entrace}
\alias{cnd_entrace}
\title{Add backtrace from error handler}
\usage{
entrace(cnd, ..., top = NULL, bottom = NULL)
cnd_entrace(cnd, ..., top = NULL, bottom = NULL)
}
\arguments{
\item{cnd}{When \code{entrace()} is used as a calling handler, \code{cnd} is
the condition to handle.}
\item{...}{Unused. These dots are for future extensions.}
\item{top}{The first frame environment to be included in the
backtrace. This becomes the top of the backtrace tree and
represents the oldest call in the backtrace.
This is needed in particular when you call \code{trace_back()}
indirectly or from a larger context, for example in tests or
inside an RMarkdown document where you don't want all of the
knitr evaluation mechanisms to appear in the backtrace.
If not supplied, the \code{rlang_trace_top_env} global option is
consulted. This makes it possible to trim the embedding context
for all backtraces created while the option is set. If knitr is
in progress, the default value for this option is
\code{knitr::knit_global()} so that the knitr context is trimmed out
of backtraces.}
\item{bottom}{The last frame environment to be included in the
backtrace. This becomes the rightmost leaf of the backtrace tree
and represents the youngest call in the backtrace.
Set this when you would like to capture a backtrace without the
capture context.
Can also be an integer that will be passed to \code{\link[=caller_env]{caller_env()}}.}
}
\description{
\code{entrace()} is a low level function. See \code{\link[=global_entrace]{global_entrace()}} for a
user-friendly way of enriching errors and other conditions from
your RProfile.
\itemize{
\item \code{entrace()} is meant to be used as a global handler. It enriches
conditions with a backtrace. Errors are saved to \code{\link[=last_error]{last_error()}}
and rethrown immediately. Messages and warnings are recorded into
\code{\link[=last_messages]{last_messages()}} and \code{\link[=last_warnings]{last_warnings()}} and let through.
\item \code{cnd_entrace()} adds a backtrace to a condition object, without
any other effect. It should be called from a condition handler.
}
\code{entrace()} also works as an \code{option(error = )} handler for
compatibility with versions of R older than 4.0.
When used as calling handler, rlang trims the handler invokation
context from the backtrace.
}
\examples{
quote({ # Not run
# Set `entrace()` globally in your RProfile
globalCallingHandlers(error = rlang::entrace)
# On older R versions which don't feature `globalCallingHandlers`,
# set the error handler like this:
options(error = rlang::entrace)
})
}
\seealso{
\code{\link[=global_entrace]{global_entrace()}} for configuring errors with
\code{entrace()}. \code{\link[=cnd_entrace]{cnd_entrace()}} to manually add a backtrace to a
condition.
}
\keyword{internal}
rlang/man/topic-condition-formatting.Rd 0000644 0001762 0000144 00000005332 14175213516 017701 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/topic-errors.R
\name{topic-condition-formatting}
\alias{topic-condition-formatting}
\title{Formatting condition messages}
\description{
Condition signallers like \code{\link[=abort]{abort()}}, \code{\link[=warn]{warn()}}, and \code{\link[=signal]{signal()}} take a character vector of \strong{bulleted text} as \code{message} argument. This makes it easy to write messages in a list format where each bullet conveys a single important point.\if{html}{\out{
}}\preformatted{abort(c(
"The error header",
"*" = "An error bullet",
"i" = "An info bullet",
"x" = "A cross bullet"
))
#> Error:
#> ! The error header
#> * An error bullet
#> i An info bullet
#> x A cross bullet
}\if{html}{\out{
}}
See the \href{https://style.tidyverse.org/error-messages.html}{tidyverse error style guide} for more about this style of error messaging.
By default, condition messages use unicode symbols rather than simple letters. This is not the case here because unicode isn't supported in documentation. If you'd like to disable unicode symbols globally, add this to your Rprofile:\if{html}{\out{
}}
\subsection{Use cli formatting}{
By default, rlang uses an internal mechanism to format bullets. It is preferable to delegate formatting to the \href{https://cli.r-lib.org/}{cli package} because it uses sophisticated paragraph wrapping and bullet indenting that make long lines easier to read. In the following example, a long \code{!} bullet is broken with an indented newline:\if{html}{\out{
}}\preformatted{rlang::global_entrace(class = "errorr")
#> Error in `rlang::global_entrace()`:
#> ! `class` must be one of "error", "warning", or "message",
#> not "errorr".
#> i Did you mean "error"?
}\if{html}{\out{
}}
To enable cli formatting, use \code{\link[cli:cli_abort]{cli::cli_abort()}}, \code{\link[cli:cli_abort]{cli::cli_warn()}}, and \code{\link[cli:cli_abort]{cli::cli_inform()}}. Not only do these wrappers improve the formatting of messages, they also add many features such as interpolation, semantic formatting of text elements, and pluralisation:\if{html}{\out{
}}\preformatted{inform_marbles <- function(n_marbles) \{
cli::cli_inform(c(
"i" = "I have \{n_marbles\} shiny marble\{?s\} in my bag.",
"v" = "Way to go \{.code cli::cli_inform()\}!"
))
\}
inform_marbles(1)
#> i I have 1 shiny marble in my bag.
#> v Way to go `cli::cli_inform()`!
inform_marbles(2)
#> i I have 2 shiny marbles in my bag.
#> v Way to go `cli::cli_inform()`!
}\if{html}{\out{
}}
}
}
\keyword{internal}
rlang/man/topic-data-mask-ambiguity.Rd 0000644 0001762 0000144 00000021147 14175213516 017377 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/topic-nse.R
\name{topic-data-mask-ambiguity}
\alias{topic-data-mask-ambiguity}
\title{The data mask ambiguity}
\description{
\link[=topic-data-mask]{Data masking} is an R feature that blends programming variables that live inside environments (env-variables) with statistical variables stored in data frames (data-variables). This mixture makes it easy to refer to data frame columns as well as objects defined in the current environment.\if{html}{\out{
}}
However this convenience introduces an ambiguity between data-variables and env-variables which might cause \strong{collisions}.
\subsection{Column collisions}{
In the following snippet, are we referring to the env-variable \code{x} or to the data-variable of the same name?\if{html}{\out{
}}\preformatted{df <- data.frame(x = NA, y = 2)
x <- 100
df \%>\% dplyr::mutate(y = y / x)
#> x y
#> 1 NA NA
}\if{html}{\out{
}}
A column collision occurs when you want to use an object defined outside of the data frame, but a column of the same name happens to exist.
}
\subsection{Object collisions}{
The opposite problem occurs when there is a typo in a data-variable name and an env-variable of the same name exists:\if{html}{\out{
}}
Instead of a typo, it might also be that you were expecting a column in the data frame which is unexpectedly missing. In both cases, if a variable can't be found in the data mask, R looks for variables in the surrounding environment. This isn't what we intended here and it would have been better to fail early with a "Column not found" error.
}
\subsection{Preventing collisions}{
In casual scripts or interactive programming, data mask ambiguity is not a huge deal compared to the payoff of iterating quickly while developing your analysis. However in production code and in package functions, the ambiguity might cause collision bugs in the long run.
Fortunately it is easy to be explicit about the scoping of variables with a little more verbose code. This topic lists the solutions and workarounds that have been created to solve ambiguity issues in data masks.
\subsection{The \code{.data} and \code{.env} pronouns}{
The simplest solution is to use the \code{\link{.data}} and \code{\link{.env}} pronouns to disambiguate between data-variables and env-variables.\if{html}{\out{
}}\preformatted{df <- data.frame(x = 1, y = 2)
x <- 100
df \%>\% dplyr::mutate(y = .data$y / .env$x)
#> x y
#> 1 1 0.02
}\if{html}{\out{
}}
This is especially useful in functions because the data frame is not known in advance and potentially contain masking columns for any of the env-variables in scope in the function:\if{html}{\out{
}}\preformatted{my_rescale <- function(data, var, factor = 10) \{
data \%>\% dplyr::mutate("\{\{ var \}\}" := \{\{ var \}\} / factor)
\}
# This works
data.frame(value = 1) \%>\% my_rescale(value)
#> value
#> 1 0.1
# Oh no!
data.frame(factor = 0, value = 1) \%>\% my_rescale(value)
#> factor value
#> 1 0 Inf
}\if{html}{\out{
}}
Subsetting function arguments with \code{.env} ensures we never hit a masking column:\if{html}{\out{
}}\preformatted{my_rescale <- function(data, var, factor = 10) \{
data \%>\% dplyr::mutate("\{\{ var \}\}" := \{\{ var \}\} / .env$factor)
\}
# Yay!
data.frame(factor = 0, value = 1) \%>\% my_rescale(value)
#> factor value
#> 1 0 0.1
}\if{html}{\out{
}}
}
\subsection{Subsetting \code{.data} with env-variables}{
The \code{\link{.data}} pronoun may be used as a name-to-data-mask pattern (see \ifelse{html}{\link[=topic-data-mask-programming]{Data mask programming patterns}}{\link[=topic-data-mask-programming]{Data mask programming patterns}}):\if{html}{\out{
}}\preformatted{var <- "cyl"
mtcars \%>\% dplyr::summarise(mean = mean(.data[[var]]))
#> # A tibble: 1 x 1
#> mean
#>
#> 1 6.19
}\if{html}{\out{
}}
In this example, the env-variable \code{var} is used inside the data mask to subset the \code{.data} pronoun. Does this mean that \code{var} is at risk of a column collision if the input data frame contains a column of the same name? Fortunately not:\if{html}{\out{
}}\preformatted{var <- "cyl"
mtcars2 <- mtcars
mtcars2$var <- "wrong"
mtcars2 \%>\% dplyr::summarise(mean = mean(.data[[var]]))
#> # A tibble: 1 x 1
#> mean
#>
#> 1 6.19
}\if{html}{\out{
}}
The evaluation of \code{.data[[var]]} is set up in such a way that there is no ambiguity. The \code{.data} pronoun can only be subsetted with env-variables, not data-variables. Technically, this is because \code{[[} behaves like an \emph{injection operator} when applied to \code{.data}. It is evaluated very early before the data mask is even created. See the \verb{!!} section below.
}
\subsection{Injecting env-variables with \verb{!!}}{
\link[=topic-inject]{Injection operators} such as \code{\link[=injection-operator]{!!}} have interesting properties regarding the ambiguity problem. They modify a piece of code early on by injecting objects or other expressions before any data-masking logic comes into play. If you inject the \emph{value} of a variable, it becomes inlined in the expression. R no longer needs to look up any variable to find the value.
Taking the earlier division example, let's use \verb{!!} to inject the value of the env-variable \code{x} inside the division expression:\if{html}{\out{
}}\preformatted{df <- data.frame(x = NA, y = 2)
x <- 100
df \%>\% dplyr::mutate(y = y / !!x)
#> x y
#> 1 NA 0.02
}\if{html}{\out{
}}
While injection solves issues of ambiguity, it is a bit heavy handed compared to using the \code{\link{.env}} pronoun. Big objects inlined in expressions might cause issues in unexpected places, for instance they might make the calls in a \code{\link[=traceback]{traceback()}} less readable.
}
}
\subsection{No ambiguity in tidy selections}{
\href{https://tidyselect.r-lib.org/reference/language.html}{Tidy selection} is a dialect of R that optimises column selection in tidyverse packages. Examples of functions that use tidy selections are \code{dplyr::select()} and \code{tidyr::pivot_longer()}.
Unlike data masking, tidy selections do not suffer from ambiguity. The selection language is designed in such a way that evaluation of expressions is either scoped in the data mask only, or in the environment only. Take this example:\if{html}{\out{
}}
\code{gear} is a symbol supplied to a selection operator \code{:} and thus scoped in the data mask only. Any other kind of expression, such as \code{ncol(mtcars)}, is evaluated as normal R code outside of any data context. This is why there is no column collision here:\if{html}{\out{
}}\preformatted{data <- data.frame(x = 1, data = 1:3)
data \%>\% dplyr::select(data:ncol(data))
#> data
#> 1 1
#> 2 2
#> 3 3
}\if{html}{\out{
}}
It is useful to introduce two new terms. Tidy selections distinguish data-expressions and env-expressions:
\itemize{
\item \code{data} is a data-expression that refers to the data-variable.
\item \code{ncol(data)} is an env-expression that refers to the env-variable.
}
To learn more about the difference between the two kinds of expressions, see the \href{https://tidyselect.r-lib.org/articles/syntax.html}{technical description of the tidy selection syntax}.
\subsection{Names pattern with \code{all_of()}}{
\code{all_of()} is often used in functions as a \link[=topic-data-mask-programming]{programming pattern} that connects column names to a data mask, similarly to the \code{\link{.data}} pronoun. A simple example is:\if{html}{\out{
}}\preformatted{my_group_by <- function(data, vars) \{
data \%>\% dplyr::group_by(across(all_of(vars)))
\}
}\if{html}{\out{
=======================================================
[](https://github.com/r-lib/rlang/actions)
[](https://app.codecov.io/gh/r-lib/rlang?branch=main)
[](https://lifecycle.r-lib.org/articles/stages.html)
rlang is a collection of frameworks and APIs for programming with R.
## Frameworks
Two comprehensive frameworks are implemented in rlang.
* __tidy eval__, a programmable [data-masking](https://rlang.r-lib.org/reference/topic-data-mask.html) framework used in tidyverse packages like dplyr and ggplot2. As a user, you will encounter the embracing operator [`{{`](https://rlang.r-lib.org/reference/embrace-operator.html) and name injection with the [glue](https://glue.tidyverse.org/) operators [`"{"`](https://rlang.r-lib.org/reference/glue-operators.html) and [`"{{"`](https://rlang.r-lib.org/reference/glue-operators.html).
* __rlang errors__, a set of tools to signal and display errors. This includes backtrace capture with `global_entrace()` and backtrace display with `last_error()` and `last_warnings()`. Use `abort()` to create errors with bullet lists, structured metadata, and error chaining support.
The display of error messages is optimised for bullet lists and chained errors and optionally integrates with the cli package (see `local_use_cli()`).
## Argument intake
A set of tools help you check, validate, and preprocess arguments.
* Checking function arguments, e.g. `arg_match()`, `check_required()`, and `check_exclusive()`.
* Checking dots, e.g. `check_dots_used()` and `check_dots_empty()`.
* Collecting [dynamic dots](https://rlang.r-lib.org/reference/dyn-dots.html), e.g. `list2()`. These dots support splicing with [`!!!`](https://rlang.r-lib.org/reference/splice-operator.html) and name injection with the [glue](https://glue.tidyverse.org/) operators [`"{"`](https://rlang.r-lib.org/reference/glue-operators.html) and [`"{{"`](https://rlang.r-lib.org/reference/glue-operators.html).
## Programming interfaces
rlang provides various interfaces for working with R and R objects.
* The R session, e.g. `check_installed()`, `on_load()`, and `on_package_load()`.
* Environments, e.g. `env()`, `env_has()`, `env_get()`, `env_bind()`, `env_unbind()`, `env_print()`, and `local_bindings()`.
* Evaluation, e.g. `inject()` and `eval_bare()`.
* Calls and symbols, e.g. `call2()`, `is_call()`, `is_call_simple()`, `data_sym()`, and `data_syms()`.
* Functions, e.g. `new_function()` and `as_function()`. The latter supports the purrr-style formula notation for lambda functions.
## Installation
Install the released version of rlang from CRAN:
```r
install.packages("rlang")
```
Or install the development version from GitHub with:
```r
# install.packages("pak")
pak::pkg_install("r-lib/rlang")
```
## Code of Conduct
Please note that the rlang project is released with a [Contributor Code of Conduct](https://rlang.r-lib.org/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.
rlang/man/ 0000755 0001762 0000144 00000000000 14176531477 012147 5 ustar ligges users rlang/man/prim_name.Rd 0000644 0001762 0000144 00000000516 14127057575 014405 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fn.R
\name{prim_name}
\alias{prim_name}
\title{Name of a primitive function}
\usage{
prim_name(prim)
}
\arguments{
\item{prim}{A primitive function such as \code{\link[base:c]{base::c()}}.}
}
\description{
Name of a primitive function
}
\keyword{internal}
rlang/man/hash.Rd 0000644 0001762 0000144 00000002716 14175213516 013355 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/hash.R
\name{hash}
\alias{hash}
\alias{hash_file}
\title{Hashing}
\usage{
hash(x)
hash_file(path)
}
\arguments{
\item{x}{An object.}
\item{path}{A character vector of paths to the files to be hashed.}
}
\value{
\itemize{
\item For \code{hash()}, a single character string containing the hash.
\item For \code{hash_file()}, a character vector containing one hash per file.
}
}
\description{
\itemize{
\item \code{hash()} hashes an arbitrary R object.
\item \code{hash_file()} hashes the data contained in a file.
}
The generated hash is guaranteed to be reproducible across platforms that
have the same endianness and are using the same R version.
}
\details{
These hashers use the XXH128 hash algorithm of the xxHash library, which
generates a 128-bit hash. Both are implemented as streaming hashes, which
generate the hash with minimal extra memory usage.
For \code{hash()}, objects are converted to binary using R's native serialization
tools. On R >= 3.5.0, serialization version 3 is used, otherwise version 2 is
used. See \code{\link[=serialize]{serialize()}} for more information about the serialization version.
}
\examples{
hash(c(1, 2, 3))
hash(mtcars)
authors <- file.path(R.home("doc"), "AUTHORS")
copying <- file.path(R.home("doc"), "COPYING")
hashes <- hash_file(c(authors, copying))
hashes
# If you need a single hash for multiple files,
# hash the result of `hash_file()`
hash(hashes)
}
rlang/man/zap_srcref.Rd 0000644 0001762 0000144 00000001534 14127057575 014575 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/attr.R
\name{zap_srcref}
\alias{zap_srcref}
\title{Zap source references}
\usage{
zap_srcref(x)
}
\arguments{
\item{x}{An R object. Functions and calls are walked recursively.}
}
\description{
There are a number of situations where R creates source references:
\itemize{
\item Reading R code from a file with \code{source()} and \code{parse()} might save
source references inside calls to \code{function} and \verb{\{}.
\item \code{\link[=sys.call]{sys.call()}} includes a source reference if possible.
\item Creating a closure stores the source reference from the call to
\code{function}, if any.
}
These source references take up space and might cause a number of
issues. \code{zap_srcref()} recursively walks through expressions and
functions to remove all source references.
}
rlang/man/scoped_interactive.Rd 0000644 0001762 0000144 00000002745 14175213516 016306 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{scoped_interactive}
\alias{scoped_interactive}
\alias{scoped_options}
\alias{scoped_bindings}
\title{Deprecated \code{scoped_} functions}
\usage{
scoped_interactive(value = TRUE, frame = caller_env())
scoped_options(..., .frame = caller_env())
scoped_bindings(..., .env = .frame, .frame = caller_env())
}
\arguments{
\item{value}{A single \code{TRUE} or \code{FALSE}. This overrides the return
value of \code{is_interactive()}.}
\item{frame}{The environment of a running function which defines
the scope of the temporary options. When the function returns,
the options are reset to their original values.}
\item{...}{For \code{local_options()} and \code{push_options()}, named
values defining new option values. For \code{peek_options()}, strings
or character vectors of option names.}
\item{.frame}{The environment of a running function which defines
the scope of the temporary options. When the function returns,
the options are reset to their original values.}
\item{.env}{An environment.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
Deprecated as of rlang 0.4.2. Use \code{\link[=local_interactive]{local_interactive()}},
\code{\link[=local_options]{local_options()}}, or \code{\link[=local_bindings]{local_bindings()}} instead.
}
\keyword{internal}
rlang/man/env_inherits.Rd 0000644 0001762 0000144 00000000655 14127057575 015137 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env.R
\name{env_inherits}
\alias{env_inherits}
\title{Does environment inherit from another environment?}
\usage{
env_inherits(env, ancestor)
}
\arguments{
\item{env}{An environment.}
\item{ancestor}{Another environment from which \code{x} might inherit.}
}
\description{
This returns \code{TRUE} if \code{x} has \code{ancestor} among its parents.
}
rlang/man/f_text.Rd 0000644 0001762 0000144 00000001320 14127057575 013721 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/formula.R
\name{f_text}
\alias{f_text}
\alias{f_name}
\alias{f_label}
\title{Turn RHS of formula into a string or label}
\usage{
f_text(x, width = 60L, nlines = Inf)
f_name(x)
f_label(x)
}
\arguments{
\item{x}{A formula.}
\item{width}{Width of each line.}
\item{nlines}{Maximum number of lines to extract.}
}
\description{
Equivalent of \code{\link[=expr_text]{expr_text()}} and \code{\link[=expr_label]{expr_label()}} for formulas.
}
\examples{
f <- ~ a + b + bc
f_text(f)
f_label(f)
# Names a quoted with ``
f_label(~ x)
# Strings are encoded
f_label(~ "a\nb")
# Long expressions are collapsed
f_label(~ foo({
1 + 2
print(x)
}))
}
rlang/man/env_binding_lock.Rd 0000644 0001762 0000144 00000003204 14175213516 015715 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-binding.R
\name{env_binding_lock}
\alias{env_binding_lock}
\alias{env_binding_unlock}
\alias{env_binding_are_locked}
\title{Lock or unlock environment bindings}
\usage{
env_binding_lock(env, nms = NULL)
env_binding_unlock(env, nms = NULL)
env_binding_are_locked(env, nms = NULL)
}
\arguments{
\item{env}{An environment.}
\item{nms}{Names of bindings. Defaults to all bindings in \code{env}.}
}
\value{
\code{env_binding_are_unlocked()} returns a logical vector as
long as \code{nms} and named after it. \code{env_binding_lock()} and
\code{env_binding_unlock()} return the old value of
\code{env_binding_are_unlocked()} invisibly.
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#experimental}{\figure{lifecycle-experimental.svg}{options: alt='[Experimental]'}}}{\strong{[Experimental]}}
Locked environment bindings trigger an error when an attempt is
made to redefine the binding.
}
\examples{
# Bindings are unlocked by default:
env <- env(a = "A", b = "B")
env_binding_are_locked(env)
# But can optionally be locked:
env_binding_lock(env, "a")
env_binding_are_locked(env)
# If run, the following would now return an error because `a` is locked:
# env_bind(env, a = "foo")
# with_env(env, a <- "bar")
# Let's unlock it. Note that the return value indicate which
# bindings were locked:
were_locked <- env_binding_unlock(env)
were_locked
# Now that it is unlocked we can modify it again:
env_bind(env, a = "foo")
with_env(env, a <- "bar")
env$a
}
\seealso{
\code{\link[=env_lock]{env_lock()}} for locking an environment.
}
\keyword{internal}
rlang/man/stack-deprecated.Rd 0000644 0001762 0000144 00000001071 14175213516 015626 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{stack-deprecated}
\alias{stack-deprecated}
\alias{ctxt_frame}
\alias{global_frame}
\title{Call stack information}
\usage{
ctxt_frame(n = 1)
global_frame()
}
\arguments{
\item{n}{The number of frames to go back in the stack.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
Deprecated as of rlang 0.3.0.
}
\keyword{internal}
rlang/man/env_name.Rd 0000644 0001762 0000144 00000002374 14127057575 014232 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-special.R
\name{env_name}
\alias{env_name}
\alias{env_label}
\title{Label of an environment}
\usage{
env_name(env)
env_label(env)
}
\arguments{
\item{env}{An environment.}
}
\description{
Special environments like the global environment have their own
names. \code{env_name()} returns:
\itemize{
\item "global" for the global environment.
\item "empty" for the empty environment.
\item "base" for the base package environment (the last environment on
the search path).
\item "namespace:pkg" if \code{env} is the namespace of the package "pkg".
\item The \code{name} attribute of \code{env} if it exists. This is how the
\link[=search_envs]{package environments} and the \link[=ns_imports_env]{imports environments} store their names. The name of package
environments is typically "package:pkg".
\item The empty string \code{""} otherwise.
}
\code{env_label()} is exactly like \code{env_name()} but returns the memory
address of anonymous environments as fallback.
}
\examples{
# Some environments have specific names:
env_name(global_env())
env_name(ns_env("rlang"))
# Anonymous environments don't have names but are labelled by their
# address in memory:
env_name(env())
env_label(env())
}
rlang/man/stack.Rd 0000644 0001762 0000144 00000002770 14175213516 013537 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stack.R
\name{stack}
\alias{stack}
\alias{current_call}
\alias{current_fn}
\alias{current_env}
\alias{caller_call}
\alias{caller_fn}
\alias{caller_env}
\alias{frame_call}
\alias{frame_fn}
\title{Get properties of the current or caller frame}
\usage{
current_call()
current_fn()
current_env()
caller_call(n = 1)
caller_fn(n = 1)
caller_env(n = 1)
frame_call(frame = caller_env())
frame_fn(frame = caller_env())
}
\arguments{
\item{n}{The number of callers to go back.}
\item{frame}{A frame environment of a currently running function,
as returned by \code{\link[=caller_env]{caller_env()}}. \code{NULL} is returned if the
environment does not exist on the stack.}
}
\description{
These accessors retrieve properties of frames on the call stack.
The prefix indicates for which frame a property should be accessed:
\itemize{
\item From the current frame with \code{current_} accessors.
\item From a calling frame with \code{caller_} accessors.
\item From a matching frame with \code{frame_} accessors.
}
The suffix indicates which property to retrieve:
\itemize{
\item \verb{_fn} accessors return the function running in the frame.
\item \verb{_call} accessors return the defused call with which the function
running in the frame was invoked.
\item \verb{_env} accessors return the execution environment of the function
running in the frame.
}
}
\seealso{
\code{\link[=caller_env]{caller_env()}} and \code{\link[=current_env]{current_env()}}
}
rlang/man/defusing-advanced.Rd 0000644 0001762 0000144 00000014011 14175213516 015770 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/nse-defuse.R
\name{defusing-advanced}
\alias{defusing-advanced}
\alias{enexpr}
\alias{exprs}
\alias{enexprs}
\alias{ensym}
\alias{ensyms}
\alias{quo}
\alias{quos}
\alias{enquo0}
\alias{enquos0}
\title{Advanced defusal operators}
\usage{
enexpr(arg)
exprs(
...,
.named = FALSE,
.ignore_empty = c("trailing", "none", "all"),
.unquote_names = TRUE
)
enexprs(
...,
.named = FALSE,
.ignore_empty = c("trailing", "none", "all"),
.unquote_names = TRUE,
.homonyms = c("keep", "first", "last", "error"),
.check_assign = FALSE
)
ensym(arg)
ensyms(
...,
.named = FALSE,
.ignore_empty = c("trailing", "none", "all"),
.unquote_names = TRUE,
.homonyms = c("keep", "first", "last", "error"),
.check_assign = FALSE
)
quo(expr)
quos(
...,
.named = FALSE,
.ignore_empty = c("trailing", "none", "all"),
.unquote_names = TRUE
)
enquo0(arg)
enquos0(...)
}
\arguments{
\item{arg}{An unquoted argument name. The expression
supplied to that argument is defused and returned.}
\item{...}{For \code{enexprs()}, \code{ensyms()} and \code{enquos()}, names of
arguments to defuse. For \code{exprs()} and \code{quos()}, expressions
to defuse.}
\item{.named}{If \code{TRUE}, unnamed inputs are automatically named
with \code{\link[=as_label]{as_label()}}. This is equivalent to applying
\code{\link[=exprs_auto_name]{exprs_auto_name()}} on the result. If \code{FALSE}, unnamed elements
are left as is and, if fully unnamed, the list is given minimal
names (a vector of \code{""}). If \code{NULL}, fully unnamed results are
left with \code{NULL} names.}
\item{.ignore_empty}{Whether to ignore empty arguments. Can be one
of \code{"trailing"}, \code{"none"}, \code{"all"}. If \code{"trailing"}, only the
last argument is ignored if it is empty. Named arguments are not
considered empty.}
\item{.unquote_names}{Whether to treat \verb{:=} as \code{=}. Unlike \code{=}, the
\verb{:=} syntax supports \link[=glue-operators]{names injection}.}
\item{.homonyms}{How to treat arguments with the same name. The
default, \code{"keep"}, preserves these arguments. Set \code{.homonyms} to
\code{"first"} to only keep the first occurrences, to \code{"last"} to keep
the last occurrences, and to \code{"error"} to raise an informative
error and indicate what arguments have duplicated names.}
\item{.check_assign}{Whether to check for \verb{<-} calls. When \code{TRUE} a
warning recommends users to use \code{=} if they meant to match a
function parameter or wrap the \verb{<-} call in curly braces otherwise.
This ensures assignments are explicit.}
\item{expr}{An expression to defuse.}
}
\description{
These advanced operators \link[=topic-defuse]{defuse} R expressions.
\code{\link[=expr]{expr()}}, \code{\link[=enquo]{enquo()}}, and \code{\link[=enquos]{enquos()}} are sufficient for most
purposes but rlang provides these other operations, either for
completeness or because they are useful to experts.
\itemize{
\item \code{exprs()} is the plural variant of \code{expr()}. It returns a list of
expressions. It is like \code{\link[base:list]{base::alist()}} but with
\link[=nse-inject]{injection} support.
\item \code{quo()} and \code{quos()} are like \code{expr()} and \code{exprs()} but return
quosures instead of naked expressions. When you are defusing
your own local expressions (by opposition to function arguments
where non-local expressions are supplied by your users), there
is generally no need to attach the current environment in a
quosure. See \ifelse{html}{\link[=topic-quosure]{What are quosures and when are they needed?}}{\link[=topic-quosure]{What are quosures and when are they needed?}}.
\item \code{enexpr()} and \code{enexprs()} are like \code{\link[=enquo]{enquo()}} and \code{\link[=enquos]{enquos()}} but
return naked expressions instead of quosures. These operators
should very rarely be used because they lose track of the
environment of defused arguments.
\item \code{ensym()} and \code{ensyms()} are like \code{enexpr()} and \code{enexprs()} but
they throw an error when the defused expressions are not simple
symbols. They also support strings which are interpreted as
symbols. These functions are modelled on the behaviour of the
left-hand side of \code{=} and \verb{<-} where you can supply symbols and
strings interchangeably.\preformatted{"foo" <- NULL
list("foo" = NULL)
}
\item \code{enquo0} and \code{enquos0()} are like \code{enquo()} and \code{enquos()} but
without injection support. The injection operators \verb{!!}, \verb{!!!},
and \verb{\{\{} are not processed, instead they are preserved in the
defused expression. This makes it possible to defuse
expressions that potentially contain injection operators meant
for later use. The trade off is that it makes it harder for
users to inject expressions in your function. They have to
enable injection explicitly with \code{\link[=inject]{inject()}}.
None of the features of \link[=dyn-dots]{dynamic dots} are available
when defusing with \code{enquos0()}. For instance, trailing empty
arguments are not automatically trimmed.
}
}
\examples{
# `exprs()` is the plural variant of `expr()`
exprs(foo, bar, bar)
# `quo()` and `quos()` are the quosure variants of `expr()` and `exprs()`
quo(foo)
quos(foo, bar)
# `enexpr()` and `enexprs()` are the naked variants of `enquo()` and `enquos()`
my_function1 <- function(arg) enexpr(arg)
my_function2 <- function(arg, ...) enexprs(arg, ...)
my_function1(1 + 1)
my_function2(1 + 1, 10 * 2)
# `ensym()` and `ensyms()` are symbol variants of `enexpr()` and `enexprs()`
my_function3 <- function(arg) ensym(arg)
my_function4 <- function(arg, ...) ensyms(arg, ...)
# The user must supply symbols
my_function3(foo)
my_function4(foo, bar)
# Complex expressions are an error
try(my_function3(1 + 1))
try(my_function4(1 + 1, 10 * 2))
# `enquo0()` and `enquos0()` disable injection operators
automatic_injection <- function(x) enquo(x)
no_injection <- function(x) enquo0(x)
automatic_injection(foo(!!!1:3))
no_injection(foo(!!!1:3))
# Injection can still be done explicitly
inject(no_injection(foo(!!!1:3)))
}
\keyword{internal}
rlang/man/env_bind.Rd 0000644 0001762 0000144 00000013520 14175213516 014211 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/env-binding.R
\name{env_bind}
\alias{env_bind}
\alias{env_bind_lazy}
\alias{env_bind_active}
\alias{\%<~\%}
\title{Bind symbols to objects in an environment}
\usage{
env_bind(.env, ...)
env_bind_lazy(.env, ..., .eval_env = caller_env())
env_bind_active(.env, ...)
lhs \%<~\% rhs
}
\arguments{
\item{.env}{An environment.}
\item{...}{<\link[=dyn-dots]{dynamic}> Named objects (\code{env_bind()}),
expressions \code{env_bind_lazy()}, or functions (\code{env_bind_active()}).
Use \code{\link[=zap]{zap()}} to remove bindings.}
\item{.eval_env}{The environment where the expressions will be
evaluated when the symbols are forced.}
\item{lhs}{The variable name to which \code{rhs} will be lazily assigned.}
\item{rhs}{An expression lazily evaluated and assigned to \code{lhs}.}
}
\value{
The input object \code{.env}, with its associated environment
modified in place, invisibly.
}
\description{
These functions create bindings in an environment. The bindings are
supplied through \code{...} as pairs of names and values or expressions.
\code{env_bind()} is equivalent to evaluating a \verb{<-} expression within
the given environment. This function should take care of the
majority of use cases but the other variants can be useful for
specific problems.
\itemize{
\item \code{env_bind()} takes named \emph{values} which are bound in \code{.env}.
\code{env_bind()} is equivalent to \code{\link[base:assign]{base::assign()}}.
\item \code{env_bind_active()} takes named \emph{functions} and creates active
bindings in \code{.env}. This is equivalent to
\code{\link[base:bindenv]{base::makeActiveBinding()}}. An active binding executes a
function each time it is evaluated. The arguments are passed to
\code{\link[=as_function]{as_function()}} so you can supply formulas instead of functions.
Remember that functions are scoped in their own environment.
These functions can thus refer to symbols from this enclosure
that are not actually in scope in the dynamic environment where
the active bindings are invoked. This allows creative solutions
to difficult problems (see the implementations of \code{dplyr::do()}
methods for an example).
\item \code{env_bind_lazy()} takes named \emph{expressions}. This is equivalent
to \code{\link[base:delayedAssign]{base::delayedAssign()}}. The arguments are captured with
\code{\link[=exprs]{exprs()}} (and thus support call-splicing and unquoting) and
assigned to symbols in \code{.env}. These expressions are not
evaluated immediately but lazily. Once a symbol is evaluated, the
corresponding expression is evaluated in turn and its value is
bound to the symbol (the expressions are thus evaluated only
once, if at all).
\item \verb{\%<~\%} is a shortcut for \code{env_bind_lazy()}. It works like \verb{<-}
but the RHS is evaluated lazily.
}
}
\section{Side effects}{
Since environments have reference semantics (see relevant section
in \code{\link[=env]{env()}} documentation), modifying the bindings of an environment
produces effects in all other references to that environment. In
other words, \code{env_bind()} and its variants have side effects.
Like other side-effecty functions like \code{par()} and \code{options()},
\code{env_bind()} and variants return the old values invisibly.
}
\examples{
# env_bind() is a programmatic way of assigning values to symbols
# with `<-`. We can add bindings in the current environment:
env_bind(current_env(), foo = "bar")
foo
# Or modify those bindings:
bar <- "bar"
env_bind(current_env(), bar = "BAR")
bar
# You can remove bindings by supplying zap sentinels:
env_bind(current_env(), foo = zap())
try(foo)
# Unquote-splice a named list of zaps
zaps <- rep_named(c("foo", "bar"), list(zap()))
env_bind(current_env(), !!!zaps)
try(bar)
# It is most useful to change other environments:
my_env <- env()
env_bind(my_env, foo = "foo")
my_env$foo
# A useful feature is to splice lists of named values:
vals <- list(a = 10, b = 20)
env_bind(my_env, !!!vals, c = 30)
my_env$b
my_env$c
# You can also unquote a variable referring to a symbol or a string
# as binding name:
var <- "baz"
env_bind(my_env, !!var := "BAZ")
my_env$baz
# The old values of the bindings are returned invisibly:
old <- env_bind(my_env, a = 1, b = 2, baz = "baz")
old
# You can restore the original environment state by supplying the
# old values back:
env_bind(my_env, !!!old)
# env_bind_lazy() assigns expressions lazily:
env <- env()
env_bind_lazy(env, name = { cat("forced!\n"); "value" })
# Referring to the binding will cause evaluation:
env$name
# But only once, subsequent references yield the final value:
env$name
# You can unquote expressions:
expr <- quote(message("forced!"))
env_bind_lazy(env, name = !!expr)
env$name
# By default the expressions are evaluated in the current
# environment. For instance we can create a local binding and refer
# to it, even though the variable is bound in a different
# environment:
who <- "mickey"
env_bind_lazy(env, name = paste(who, "mouse"))
env$name
# You can specify another evaluation environment with `.eval_env`:
eval_env <- env(who = "minnie")
env_bind_lazy(env, name = paste(who, "mouse"), .eval_env = eval_env)
env$name
# Or by unquoting a quosure:
quo <- local({
who <- "fievel"
quo(paste(who, "mouse"))
})
env_bind_lazy(env, name = !!quo)
env$name
# You can create active bindings with env_bind_active(). Active
# bindings execute a function each time they are evaluated:
fn <- function() {
cat("I have been called\n")
rnorm(1)
}
env <- env()
env_bind_active(env, symbol = fn)
# `fn` is executed each time `symbol` is evaluated or retrieved:
env$symbol
env$symbol
eval_bare(quote(symbol), env)
eval_bare(quote(symbol), env)
# All arguments are passed to as_function() so you can use the
# formula shortcut:
env_bind_active(env, foo = ~ runif(1))
env$foo
env$foo
}
\seealso{
\code{\link[=env_poke]{env_poke()}} for binding a single element.
}
rlang/man/call_modify.Rd 0000644 0001762 0000144 00000005632 14175213516 014714 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/call.R
\name{call_modify}
\alias{call_modify}
\title{Modify the arguments of a call}
\usage{
call_modify(
.call,
...,
.homonyms = c("keep", "first", "last", "error"),
.standardise = NULL,
.env = caller_env()
)
}
\arguments{
\item{.call}{Can be a call, a formula quoting a call in the
right-hand side, or a frame object from which to extract the call
expression.}
\item{...}{<\link[=dyn-dots]{dynamic}> Named or unnamed expressions
(constants, names or calls) used to modify the call. Use \code{\link[=zap]{zap()}}
to remove arguments. Empty arguments are preserved.}
\item{.homonyms}{How to treat arguments with the same name. The
default, \code{"keep"}, preserves these arguments. Set \code{.homonyms} to
\code{"first"} to only keep the first occurrences, to \code{"last"} to keep
the last occurrences, and to \code{"error"} to raise an informative
error and indicate what arguments have duplicated names.}
\item{.standardise, .env}{Deprecated as of rlang 0.3.0. Please
call \code{\link[=call_match]{call_match()}} manually.}
}
\value{
A quosure if \code{.call} is a quosure, a call otherwise.
}
\description{
If you are working with a user-supplied call, make sure the
arguments are standardised with \code{\link[=call_match]{call_match()}} before
modifying the call.
}
\examples{
call <- quote(mean(x, na.rm = TRUE))
# Modify an existing argument
call_modify(call, na.rm = FALSE)
call_modify(call, x = quote(y))
# Remove an argument
call_modify(call, na.rm = zap())
# Add a new argument
call_modify(call, trim = 0.1)
# Add an explicit missing argument:
call_modify(call, na.rm = )
# Supply a list of new arguments with `!!!`
newargs <- list(na.rm = NULL, trim = 0.1)
call <- call_modify(call, !!!newargs)
call
# Remove multiple arguments by splicing zaps:
newargs <- rep_named(c("na.rm", "trim"), list(zap()))
call <- call_modify(call, !!!newargs)
call
# Modify the `...` arguments as if it were a named argument:
call <- call_modify(call, ... = )
call
call <- call_modify(call, ... = zap())
call
# When you're working with a user-supplied call, standardise it
# beforehand in case it includes unmatched arguments:
user_call <- quote(matrix(x, nc = 3))
call_modify(user_call, ncol = 1)
# `call_match()` applies R's argument matching rules. Matching
# ensures you're modifying the intended argument.
user_call <- call_match(user_call, matrix)
user_call
call_modify(user_call, ncol = 1)
# By default, arguments with the same name are kept. This has
# subtle implications, for instance you can move an argument to
# last position by removing it and remapping it:
call <- quote(foo(bar = , baz))
call_modify(call, bar = NULL, bar = missing_arg())
# You can also choose to keep only the first or last homonym
# arguments:
args <- list(bar = NULL, bar = missing_arg())
call_modify(call, !!!args, .homonyms = "first")
call_modify(call, !!!args, .homonyms = "last")
}
rlang/man/zap.Rd 0000644 0001762 0000144 00000001522 14127057575 013226 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/s3.R
\name{zap}
\alias{zap}
\alias{is_zap}
\title{Create zap objects}
\usage{
zap()
is_zap(x)
}
\arguments{
\item{x}{An object to test.}
}
\description{
\code{zap()} creates a sentinel object that indicates that an object
should be removed. For instance, named zaps instruct \code{\link[=env_bind]{env_bind()}}
and \code{\link[=call_modify]{call_modify()}} to remove those objects from the environment or
the call.
The advantage of zap objects is that they unambiguously signal the
intent of removing an object. Sentinels like \code{NULL} or
\code{\link[=missing_arg]{missing_arg()}} are ambiguous because they represent valid R
objects.
}
\examples{
# Create one zap object:
zap()
# Create a list of zaps:
rep(list(zap()), 3)
rep_named(c("foo", "bar"), list(zap()))
}
rlang/man/is_condition.Rd 0000644 0001762 0000144 00000000575 14175213516 015114 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd.R
\name{is_condition}
\alias{is_condition}
\alias{is_error}
\alias{is_warning}
\alias{is_message}
\title{Is object a condition?}
\usage{
is_condition(x)
is_error(x)
is_warning(x)
is_message(x)
}
\arguments{
\item{x}{An object to test.}
}
\description{
Is object a condition?
}
\keyword{internal}
rlang/man/scoped_env.Rd 0000644 0001762 0000144 00000001322 14175213516 014547 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lifecycle-deprecated.R
\name{scoped_env}
\alias{scoped_env}
\alias{is_scoped}
\title{Deprecated \code{scoped} functions}
\usage{
scoped_env(nm)
is_scoped(nm)
}
\arguments{
\item{nm}{The name of an environment attached to the search
path. Call \code{\link[base:search]{base::search()}} to see what is currently on the path.}
}
\description{
\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}}
These functions are deprecated as of rlang 0.3.0. Please use
\code{\link[=is_attached]{is_attached()}} instead.
}
\keyword{internal}
rlang/man/cnd_message.Rd 0000644 0001762 0000144 00000006022 14175213516 014674 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/cnd-message.R
\name{cnd_message}
\alias{cnd_message}
\alias{cnd_header}
\alias{cnd_body}
\alias{cnd_footer}
\title{Build an error message from parts}
\usage{
cnd_message(cnd, ..., inherit = TRUE, prefix = FALSE)
cnd_header(cnd, ...)
cnd_body(cnd, ...)
cnd_footer(cnd, ...)
}
\arguments{
\item{cnd}{A condition object.}
\item{...}{Arguments passed to methods.}
\item{inherit}{Wether to include parent messages. Parent messages
are printed with a "Caused by error:" prefix, even if \code{prefix} is
\code{FALSE}.}
\item{prefix}{Whether to print the full message, including the
condition prefix (\verb{Error:}, \verb{Warning:}, \verb{Message:}, or
\verb{Condition:}). The prefix mentions the \code{call} field if present,
and the \code{srcref} info if present. If \code{cnd} has a \code{parent} field
(i.e. the condition is chained), the parent messages are included
in the message with a \verb{Caused by} prefix.}
}
\description{
\code{cnd_message()} assembles an error message from three generics:
\itemize{
\item \code{cnd_header()}
\item \code{cnd_body()}
\item \code{cnd_footer()}
}
Methods for these generics must return a character vector. The
elements are combined into a single string with a newline
separator. Bullets syntax is supported, either through rlang (see
\code{\link[=format_error_bullets]{format_error_bullets()}}), or through cli if the condition has
\code{use_cli_format} set to \code{TRUE}.
The default method for the error header returns the \code{message} field
of the condition object. The default methods for the body and
footer return the the \code{body} and \code{footer} fields if any, or empty
character vectors otherwise.
\code{cnd_message()} is automatically called by the \code{conditionMessage()}
for rlang errors, warnings, and messages. Error classes created
with \code{\link[=abort]{abort()}} only need to implement header, body or footer
methods. This provides a lot of flexibility for hierarchies of
error classes, for instance you could inherit the body of an error
message from a parent class while overriding the header and footer.
}
\section{Overriding header, body, and footer methods}{
Sometimes the contents of an error message depends on the state of
your checking routine. In that case, it can be tricky to lazily
generate error messages with \code{cnd_header()}, \code{cnd_body()}, and
\code{cnd_footer()}: you have the choice between overspecifying your
error class hierarchies with one class per state, or replicating
the type-checking control flow within the \code{cnd_body()} method. None
of these options are ideal.
A better option is to define \code{header}, \code{body}, or \code{footer} fields
in your condition object. These can be a static string, a
\link[=as_function]{lambda-formula}, or a function with the same
signature as \code{cnd_header()}, \code{cnd_body()}, or \code{cnd_footer()}. These
fields override the message generics and make it easy to generate
an error message tailored to the state in which the error was
constructed.
}
rlang/man/topic-multiple-columns.Rd 0000644 0001762 0000144 00000014375 14175213516 017063 0 ustar ligges users % Generated by roxygen2: do not edit by hand
% Please edit documentation in R/topic-nse.R
\name{topic-multiple-columns}
\alias{topic-multiple-columns}
\title{Taking multiple columns without \code{...}}
\description{
In this guide we compare ways of taking multiple columns in a single function argument.
As a refresher (see the \link[=topic-data-mask-programming]{programming patterns} article), there are two common ways of passing arguments to \link[=topic-data-mask]{data-masking} functions. For single arguments, embrace with \ifelse{html}{\code{\link[=embrace-operator]{\{\{}}}{\verb{\{\{}}:\if{html}{\out{