diff --git a/DESCRIPTION b/DESCRIPTION index 1845ede36..e9d805dac 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -55,7 +55,6 @@ Collate: 'exports.R' 'glimpse.R' 'has-name.R' - 'tibble.R' 'lst.R' 'msg-format.R' 'msg.R' @@ -65,6 +64,7 @@ Collate: 'strrep.R' 'tbl-df.r' 'tibble-package.R' + 'tibble.R' 'type-sum.r' 'utils-format.r' 'utils.r' diff --git a/R/lst.R b/R/lst.R index 0df4a9bc8..083bd49ec 100644 --- a/R/lst.R +++ b/R/lst.R @@ -1,15 +1,39 @@ -#' @include tibble.R +#' Build a list #' #' @description #' -#' `lst()` is similar to [list()], but like `tibble()`, it -#' evaluates its arguments lazily and in order, and automatically adds names. +#' `lst()` constructs a list, similar to [base::list()], but with some of the +#' same features as [tibble()]. `lst()` evaluates its arguments lazily and in +#' order. It also generates missing names automatically. #' -#' `lst_()` uses lazy evaluation and is deprecated. New code should use `lst()` -#' with [quasiquotation]. +#' @section Life cycle: #' +#' `lst()` is stable. +#' +#' `lst_()` uses an older approach to lazy evaluation that predates the tidy +#' eval framework. It is deprecated. New code should use `lst()` with +#' [quasiquotation]. +#' +#' @inheritParams tibble +#' @return A named list. #' @export -#' @rdname tibble +#' @examples +#' # the value of n can be used immediately in the definition of x +#' lst(n = 5, x = runif(n)) +#' +#' # missing names are constructed from user's input +#' lst(1:3, z = letters[4:6], runif(3)) +#' +#' # pre-formed quoted expressions can be used with lst() and then +#' # unquoted (with !!) or unquoted and spliced (with !!!) +#' n1 <- 2 +#' n2 <- 3 +#' n_stuff <- quote(n1 + n2) +#' x_stuff <- quote(seq_len(n)) +#' lst(!!!list(n = n_stuff, x = x_stuff)) +#' lst(n = !!n_stuff, x = !!x_stuff) +#' lst(n = 4, x = !!x_stuff) +#' lst(!!!list(n = 2, x = x_stuff)) lst <- function(...) { xs <- quos(..., .named = TRUE) lst_quos(xs) @@ -67,7 +91,7 @@ expand_vecs <- function(x, length) { #' @export #' @usage NULL -#' @rdname tibble +#' @rdname lst lst_ <- function(xs) { xs <- compat_lazy_dots(xs, caller_env()) lst(!!!xs) diff --git a/R/tibble.R b/R/tibble.R index b48c7d580..082aeefe3 100644 --- a/R/tibble.R +++ b/R/tibble.R @@ -1,4 +1,4 @@ -#' Build a data frame or list +#' Build a data frame #' #' @description #' `tibble()` is a trimmed down version of [data.frame()] that: @@ -12,7 +12,7 @@ #' * Adds `tbl_df` class to output. #' #' @param ... A set of name-value pairs. Arguments are evaluated sequentially, -#' so you can refer to previously created variables. These arguments are +#' so you can refer to previously created elements. These arguments are #' processed with [rlang::quos()] and support unquote via `!!` and #' unquote-splice via [`!!!`]. #' @param .rows The number of rows, useful to create a 0-column tibble or @@ -102,12 +102,6 @@ #' # You can splice-unquote a list of quosures and expressions: #' tibble(!!!list(x = rlang::quo(1:10), y = quote(x * 2))) #' -#' # lst() behaves very similarly, without restriction on the length -#' # of the individual elements: -#' lst(n = 5, x = runif(n)) -#' -#' lst(!!!list(n = rlang::quo(2 + 3), y = quote(runif(n)))) -#' #' @aliases tbl_df-class tibble <- function(..., .rows = NULL, diff --git a/man/lst.Rd b/man/lst.Rd new file mode 100644 index 000000000..41d44bf24 --- /dev/null +++ b/man/lst.Rd @@ -0,0 +1,51 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/lst.R +\name{lst} +\alias{lst} +\alias{lst_} +\title{Build a list} +\usage{ +lst(...) +} +\arguments{ +\item{...}{A set of name-value pairs. Arguments are evaluated sequentially, +so you can refer to previously created elements. These arguments are +processed with \code{\link[rlang:quos]{rlang::quos()}} and support unquote via \code{!!} and +unquote-splice via \code{\link{!!!}}.} +} +\value{ +A named list. +} +\description{ +\code{lst()} constructs a list, similar to \code{\link[base:list]{base::list()}}, but with some of the +same features as \code{\link[=tibble]{tibble()}}. \code{lst()} evaluates its arguments lazily and in +order. It also generates missing names automatically. +} +\section{Life cycle}{ + + +\code{lst()} is stable. + +\code{lst_()} uses an older approach to lazy evaluation that predates the tidy +eval framework. It is deprecated. New code should use \code{lst()} with +\link{quasiquotation}. +} + +\examples{ +# the value of n can be used immediately in the definition of x +lst(n = 5, x = runif(n)) + +# missing names are constructed from user's input +lst(1:3, z = letters[4:6], runif(3)) + +# pre-formed quoted expressions can be used with lst() and then +# unquoted (with !!) or unquoted and spliced (with !!!) +n1 <- 2 +n2 <- 3 +n_stuff <- quote(n1 + n2) +x_stuff <- quote(seq_len(n)) +lst(!!!list(n = n_stuff, x = x_stuff)) +lst(n = !!n_stuff, x = !!x_stuff) +lst(n = 4, x = !!x_stuff) +lst(!!!list(n = 2, x = x_stuff)) +} diff --git a/man/tibble.Rd b/man/tibble.Rd index 016a7c8a6..45ede10c9 100644 --- a/man/tibble.Rd +++ b/man/tibble.Rd @@ -1,20 +1,16 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/tibble.R, R/lst.R +% Please edit documentation in R/tibble.R \name{tibble} \alias{tibble} \alias{tbl_df-class} -\alias{lst} -\alias{lst_} -\title{Build a data frame or list} +\title{Build a data frame} \usage{ tibble(..., .rows = NULL, .name_repair = c("check_unique", "unique", "syntactic", "minimal")) - -lst(...) } \arguments{ \item{...}{A set of name-value pairs. Arguments are evaluated sequentially, -so you can refer to previously created variables. These arguments are +so you can refer to previously created elements. These arguments are processed with \code{\link[rlang:quos]{rlang::quos()}} and support unquote via \code{!!} and unquote-splice via \code{\link{!!!}}.} @@ -46,12 +42,6 @@ to enforce them.} \item Evaluates its arguments lazily and in order. \item Adds \code{tbl_df} class to output. } - -\code{lst()} is similar to \code{\link[=list]{list()}}, but like \code{tibble()}, it -evaluates its arguments lazily and in order, and automatically adds names. - -\code{lst_()} uses lazy evaluation and is deprecated. New code should use \code{lst()} -with \link{quasiquotation}. } \examples{ # Unnamed arguments are named with their expression: @@ -123,12 +113,6 @@ try(tibble(a = 1:3, b = tibble(c = 4:7))) # You can splice-unquote a list of quosures and expressions: tibble(!!!list(x = rlang::quo(1:10), y = quote(x * 2))) -# lst() behaves very similarly, without restriction on the length -# of the individual elements: -lst(n = 5, x = runif(n)) - -lst(!!!list(n = rlang::quo(2 + 3), y = quote(runif(n)))) - } \seealso{ \code{\link[=as_tibble]{as_tibble()}} to turn an existing list into a data frame,