README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# tidyview

The goal of tidyview is to provide an extensible replacement for `utils::View()`.

## Installation

You can install the released version of tidyview from [CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("tidyview")
```

## Example

By default, `view()` forwards to `utils::View()`.
This isn't useful for rendering an _rmarkdown_ document, so the first code shown here will be how to turn it off.

```{r setup-suppress}
library(tidyview)
suppress_view()
```

Now we're safe to use `view()`:

```{r}
library(tidyverse)

view(mtcars)

mtcars %>%
  view() %>%
  nrow()
```

Note the pipe-friendlyness -- the input is passed through, invisibly, and can be processed later on.
In an interactive session, the code above would have opened two data viewers, via the `default_view_handler()` function:

```{r default}
default_view_handler
```

Custom view handlers can be made available through _factories_.
The factory is a design pattern, see the [Wikipedia article](https://en.wikipedia.org/wiki/Factory_(object-oriented_programming)) if you're not familiar with it.

1. A factory is registered via `register_view_handler_factory()`.

1. Each time `view()` is called, all registered factories are consulted.

1. The first factory that returns a valid handler, i.e. a function similar to the `default_view_handler()` seen above, wins. The handler is called with the object.

1. If no factory takes responsibility, the default view handler is used.

The factory must be a pure function without (user-visible) side effects!

We register a view handler factory that outputs the title and the dimensions of the object for 2D objects, and does nothing for all other objects.

```{r factory}
my_view_handler_factory <- function(x) {
  if (length(dim(x)) != 2) return (NULL)
  
  my_view_handler
}

my_view_handler <- function(x, title) {
  cat("Title: ", title, "\n", sep = "")
  cat("Dimensions: ", paste(dim(x), collapse = " x "), "\n", sep = "")
}

register_view_handler_factory(my_view_handler_factory)
```

Now, when we `view()` a data frame, we get console output:

```{r view-console}
view(mtcars)

mtcars %>%
  view() %>%
  nrow()

mtcars %>%
  view("my title")
```

(The dot `.` in the title is created by the pipe. If you need to distinguish views in a pipe-based workflow, use the `title` argument to `view()`.)

Viewing a vector still doesn't do anything, this is how we designed our view handler factory:

```{r view-vector}
view(1:10)
```

The implementation of `suppress_view()` shouldn't be surprising:

```{r suppress-implementation}
suppress_view
```

Factories are consulted in reverse registration order, calling `suppress_view()` again moves the void handler factory to the top.

```{r view-suppress-again}
suppress_view()
view(mtcars)
```