# Upgrading to pins 1.0.0

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.

    library(pins)

## Examples

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

    # 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()`.

    # 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:

    # 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:

    # 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()`:

    # 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:

    # 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()`:

    # 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:

    # 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()`:

    # 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()`