pins-update.Rmd

---
title: "Upgrading to pins 1.0.0"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Upgrading to pins 1.0.0}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
---

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

pins 1.0.0 introduced a completely new API and the old legacy API was deprecated in pins 1.4.0, so now is a good time to switch to the new interface.
This vignette shows a couple of examples of updating legacy code to the modern API, then provides a full set of equivalences between the legacy and modern function names.

```{r setup}
library(pins)
```

## Examples

A simple example of the legacy API looks something like this:

```{r}
# Legacy API
board_register_local("vignette", tempfile())

pin(head(mtcars), "mtcars", board = "vignette")
pin_get("mtcars", board = "vignette")
```

To convert to the modern API you need to make two major changes:

-   Instead of registering a named board, you create an explicit board object.
-   You use `pin_read()` and `pin_write()` instead of `pin_get()` and `pin()`.

```{r}
# Modern API
board <- board_local()

pin_write(board, head(mtcars), "mtcars")
pin_read(board, "mtcars")
```

Since the board object is always the first argument, you might also want to use the pipe:

```{r, echo=FALSE}
Sys.sleep(1)
```

```{r}
# Modern API
board <- board_local()

board %>% pin_write(head(mtcars), "mtcars")
board %>% pin_read("mtcars")
```

### Pinning files

Another way to use `pin()` is with a path to a file:

```{r}
# Legacy API
path <- tempfile()
writeLines(letters, path)

pin(path, "alphabet", board = "vignette")
pin_get("alphabet", board = "vignette")
```

pins 1.0.0 clearly separates the two cases of pin an object and pinning a file, so here instead of `pin_write()` and `pin_read()` you need to `pin_upload()` and `pin_download()`:

```{r}
# Modern API
board %>% pin_upload(path, "alphabet")
board %>% pin_download("alphabet")
```

### Pinning a url

Finally, you can `pin()` a url to automatically re-download it when it changes:

```{r}
# Legacy API
base <- "https://raw.githubusercontent.com/rstudio/pins-r/main/tests/testthat/"

(pin(paste0(base, "pin-files/first.txt"), board = "vignette"))
```

This now needs to be made explicit with the new `board_url()`, and since this returns a path, not a file, you need to use `pin_download()`:

```{r}
# Modern API
board_github <- board_url(c(
  raw = paste0(base, "pin-files/first.txt")
))
board_github %>% pin_download("raw")
```

### Implicit board

It's also possible to use `pin()` and `pin_get()` without an explicit board argument, in which case it automatically uses a local board:

```{r}
# Legacy API
pin(data.frame(x = 1:3), "test-data")
pin_get("test-data")
```

To convert this code, you need to create an explicit `board_local()`:

```{r}
# Modern API
board <- board_local()

board %>% pin_write(data.frame(x = 1:3), "test-data")
board %>% pin_read("test-data")
```

## Equivalents

### Board functions

| Legacy API                   | Modern API                                              |
|------------------------------|---------------------------------------------------------|
| `board_register_azure()`     | `board_azure()`                                         |
| `board_register_datatxt()`   | Not currently implemented                               |
| `board_register_dospace()`   | Not currently implemented                               |
| `board_register_gcloud()`    | `board_gcs()`                                           |
| `board_register_github()`    | Use `board_folder()` together with `board_url()`        |
| `board_register_local()`     | `board_local()`                                         |
| `board_register_kaggle()`    | `board_kaggle_dataset()` / `board_kaggle_competition()` |
| `board_register_rsconnect()` | `board_connect()`                                       |
| `board_register_s3()`        | `board_s3()`                                            |
| `pin()` with a URL           | `board_url()`                                           |

Future releases will add support for additional boards based on user feedback.

### Pin functions

| Legacy API       | Modern API                                        |
|------------------|---------------------------------------------------|
| `board_browse()` | `pin_browse()`                                    |
| `pin()`          | `pin_write()` / `pin_upload()`                    |
| `pin_get()`      | `pin_read()` / `pin_download()`                   |
| `pin_find()`     | `pin_search()`                                    |
| `pin_info()`     | `pin_meta()`                                      |
| `pin_reactive()` | `pin_reactive_read()` / `pin_reactive_download()` |
| `pin_remove()`   | `pin_delete()`                                    |