---
title: "wrapr Eager Evaluation"
author: "John Mount, Win-Vector LLC"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{wrapr Eager Evaluation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

[`wrapr`](https://github.com/WinVector/wrapr) dot arrow piping is designed to emphasize a `a %.>% b` "is nearly" `{. <- a; b}` semantics.  In many cases this makes a piped expression of the form `a %.>% b(.)` look very much like `b(a)`.  This leads to the observation that "wrapr explicit dot notation" appears to need one more dot than the common "[`magrittr`]( https://CRAN.R-project.org/package=magrittr) dot is a new implicit first argument notation."

There are some special rules around things like names.  For example `5 %.>% sin` is *not* valued as `sin`, which would be the strict interpretation of `{. <- 5; sin}`.  Instead it is expanded to something closer `{. <- 5; sin(.)}`, which intentionally looks very much like `sin(5)`. In more complicated cases the user can signal they wish for an eager evaluation of this style by writing on outer `.()` container.

And `wrapr` now also exposes an "eager" annotation such that function evaluations or array indexing operations so-annotated are interpreted as `a %.>% f(...)` is interpreted roughly as `{. <- a; _f <- eval(f(...)); _f(.)}`, where `_f` is a notional temporary variable (not visible or produces as a side-effect).  This effect is used in `wrapr`'s "pipe to array" variation of the `unpack` notation (example [here](https://win-vector.com/2020/01/21/using-unpack-to-manage-your-r-environment/)).

This eager effect can be gotten by setting the appropriate attribute as we see below.

For array notation:

```{r}
library(wrapr)
```

```{r}
lst <- list(sin)

# without the attribute, the function is returned
4 %.>% lst[[1]]
```

```{r}
# an outer .() signals for eager eval from the pipeline
4 %.>% .(lst[[1]])
```


```{r}
# with the attribute, the array is always de-referenced
# before the pipe execution allowing the function
# to be evaluated using the piped-in value.
attr(lst, 'dotpipe_eager_eval_bracket') <- TRUE

4 %.>% lst[[1]]
```

For functions:
  
```{r}
# without the attribute the result is sin
f <- function(...) { sin }
4 %.>% f()
```

```{r}
# an outer .() signals for eager eval from the pipeline
4 %.>% .(f())
```

```{r}
# with the attribute the result is sin(4)
attr(f, 'dotpipe_eager_eval_function') <- TRUE

4 %.>% f()
```

Essentially objects with this attribute have an implicit `.()` "eager eval" on them.