Skip to contents

pinsManifest

The goal of pinsManifest is to help with a particular use-case for pins:

The mechanism is to make a manifest file of pins used to create a pins::board_url().

It is hoped that this package can motivate a discussion to see if these ideas could be integrated into the pins package itself. In other words, one version of success is that this package need not exist.

Installation

You can install the development version of pinsManifest from GitHub with:

# install.packages("devtools")
devtools::install_github("ijlyttle/pinsManifest")

Example

Writing a folder-board

Let’s say you have a pins::board_folder() that you want to serve as a website, perhaps using GitHub. You can write a manifest file for the pins using pin_write_manifest():

board <- pins::board_folder("/some/path")

# add/update pins

pin_write_manifest(board)
#> Manifest file written to `/some/path/_pins.yaml`

This writes a manifest file, _pins.yaml to root directory of your board. It stores the names of your pins and the names of each version of each pin.

Note: pin_write_manifest() supports only boards created using pins::board_folder().

Reading a URL-board

To create a pins::board_url(), you need a named character-vector where:

  • names are names of pins
  • values are the URLs that point to a version-directory

The problem is that the names of version directories are, by design, hard to predict and manage manually.

This is where a manifest file, _pins.yaml can help. When you call board_url_manifest(), it downloads _pins.yaml, then parses it to provide information to build a pins::board_url().

A demonstration board is provided using url_demo_manifest():

board_demo <- board_url_manifest(url_demo_manifest())

pins::pin_list(board_demo)
#> [1] "mtcars-csv"  "mtcars-json"
pins::pin_meta(board_demo, "mtcars-json")
#> List of 11
#>  $ file       : chr "mtcars-json.json"
#>  $ file_size  : 'fs_bytes' int 4.05K
#>  $ pin_hash   : chr "c2702fb156ba5c38"
#>  $ type       : chr "json"
#>  $ title      : chr "mtcars-json: a pinned 32 x 11 data frame"
#>  $ description: NULL
#>  $ created    : POSIXct[1:1], format: "2022-08-06 19:58:00"
#>  $ api_version: num 1
#>  $ user       : list()
#>  $ name       : chr "mtcars-json"
#>  $ local      :List of 4
#>   ..$ dir     : 'fs_path' chr "~/Library/Caches/pins/url/94f8727184d79b18fa08f804cec2f2d5"
#>   ..$ url     : chr "https://raw.githubusercontent.com/ijlyttle/pinsManifest/main/tests/testthat/pins/mtcars-json/20220807T005818Z-c2702/"
#>   ..$ version : NULL
#>   ..$ file_url: chr "https://raw.githubusercontent.com/ijlyttle/pinsManifest/main/tests/testthat/pins/mtcars-json/20220807T005818Z-c"| __truncated__

Behind the scenes

The function manifest_latest():

  • takes a url describing the root directory of a board
  • downloads and parses the _pins.yaml file at the root
  • returns a named character vector where:
    • names are names of pins
    • values are URLs to directory for the latest version for each pin

The return value can be used to build a pins::board_url():

manifest_latest(url_demo_manifest())
#>                                                                                                             mtcars-csv 
#>  "https://raw.githubusercontent.com/ijlyttle/pinsManifest/main/tests/testthat/pins/mtcars-csv/20220807T005820Z-48c73/" 
#>                                                                                                            mtcars-json 
#> "https://raw.githubusercontent.com/ijlyttle/pinsManifest/main/tests/testthat/pins/mtcars-json/20220807T005818Z-c2702/"