pins (version 1.1.0)

board_url: Use a vector of URLs as a board

Description

board_url() lets you build up a board from individual urls or a manifest file.

board_url() is read only.

Usage

board_url(urls, cache = NULL, use_cache_on_failure = is_interactive())

Arguments

urls

Identify available pins being served at a URL or set of URLs (see details):

• Unnamed string: URL to a manifest file.

• Named character vector: URLs to specific pins (does not support versioning).

• Named list: URLs to pin version directories (supports versioning).

cache

Cache path. Every board requires a local cache to avoid downloading files multiple times. The default stores in a standard cache location for your operating system, but you can override if needed.

use_cache_on_failure

If the pin fails to download, is it ok to use the last cached version? Defaults to is_interactive() so you'll be robust to poor internet connectivity when exploring interactively, but you'll get clear errors when the code is deployed.

Details

The way board_url() works depends on the type of the urls argument:

• Unnamed character scalar, i.e. a single URL to a manifest file: If the URL ends in a /, board_url() will look for a _pins.yaml manifest. If the manifest file parses to a named list, versioning is supported. If it parses to a named character vector, the board will not support versioning.

• Named character vector of URLs: If the URLs end in a /, board_url() will look for a data.txt that provides metadata for the associated pin. The easiest way to generate this file is to upload a pin version directory created by board_folder(). Versioning is not supported.

• Named list, where the values are character vectors of URLs and each element of the vector refers to a version of the particular pin: If a URL ends in a /, board_url() will look for a data.txt that provides metadata. Versioning is supported.

Using a vector of URLs can be useful because pin_download() and pin_read() will be cached; they'll only re-download the data if it's changed from the last time you downloaded it (using the tools of HTTP caching). You'll also be protected from the vagaries of the internet; if a fresh download fails, you'll get the previously cached result with a warning.

Using a manifest file can be useful because you can serve a board of pins and allow collaborators to access the board straight from a URL, without worrying about board-level storage details.

Some examples are provided in vignette("using-board-url").

See Also

Other boards: board_connect(), board_folder()

Examples

github_raw <- function(x) paste0("https://raw.githubusercontent.com/", x)

## with a named vector of URLs to specific pins:
b1 <- board_url(c(
  files = github_raw("rstudio/pins-r/main/tests/testthat/pin-files/"),
  rds = github_raw("rstudio/pins-r/main/tests/testthat/pin-rds/"),
  raw = github_raw("rstudio/pins-r/main/tests/testthat/pin-files/first.txt")
))

b1 %>% pin_read("rds")
b1 %>% pin_browse("rds", local = TRUE)

b1 %>% pin_download("files")
b1 %>% pin_download("raw")

## with a manifest file:
b2 <- board_url(github_raw("rstudio/pins-r/main/tests/testthat/pin-board/"))
b2 %>% pin_list()
b2 %>% pin_versions("y")