gistr introduction

Scott Chamberlain

2020年07月28日

Install

Stable version from CRAN

install.packages("gistr")

Development version from GitHub

remotes::install_github("ropensci/gistr")

library("gistr")

Authentication

There are two ways to authorise gistr to work with your GitHub account:

Generate a personal access token (PAT) with the gist scope selected at https://help.github.com/articles/creating-an-access-token-for-command-line-use and record it in the GITHUB_PAT environment variable.
- To test out this approach, execute this in R: Sys.setenv(GITHUB_PAT = "blahblahblah"), where "blahblahblah" is the PAT you got from GitHub. Then take gistr out for a test drive.
- If that works, you will probably want to define the GITHUB_PAT environment variable in a file such as ~/.bash_profile or ~/.Renviron.
Interactively login into your GitHub account and authorise with OAuth.

Using the PAT is recommended.

Using the gist_auth() function you can authenticate separately first, or if you’re not authenticated, this function will run internally with each function call. If you have a PAT, that will be used, if not, OAuth will be used.

gist_auth()

Workflow

In gistr you can use pipes, introduced perhaps first in R in the package magrittr, to pass outputs from one function to another. If you have used dplyr with pipes you can see the difference, and perhaps the utility, of this workflow over the traditional workflow in R. You can use a non-piping or a piping workflow with gistr. Examples below use a mix of both workflows. Here is an example of a piping workflow (with some explanation):

file <-system.file("examples", "alm.md", package = "gistr")
gists(what = "minepublic")[[1]] %>%# List my public gists, and index to get just the 1st one
add_files(file) %>%# Add a new file to that gist
update() # update sends a PATCH command to the Gists API to add the file to your gist online

And a non-piping workflow that does the same exact thing:

file <-system.file("examples", "alm.md", package = "gistr")
g <-gists(what = "minepublic")[[1]]
g <-add_files(g, file)
update(g)

Or you could string them all together in one line (but it’s rather difficult to follow what’s going on because you have to read from the inside out)

file <-system.file("examples", "alm.md", package = "gistr")
update(add_files(gists(what = "minepublic")[[1]], file))

Rate limit information

rate_limit()
#> Rate limit: 5000
#> Remaining: 4998
#> Resets in: 59 minutes

List gists

Limiting to a few results here to keep it brief

gists(per_page = 2)
#> [[1]]
#> <gist>721a433293af4cb1fb0f66d7ccb37339
#> URL: https://gist.github.com/721a433293af4cb1fb0f66d7ccb37339
#> Description: Atividades 8o Ano
#> Public: TRUE
#> Created/Edited: 2020年07月28日T20:18:22Z / 2020年07月28日T20:18:23Z
#> Files: 8o_ano.md
#> Truncated?: FALSE
#> 
#> [[2]]
#> <gist>d1064ad4f7fa9cd30b4409ade98fbd92
#> URL: https://gist.github.com/d1064ad4f7fa9cd30b4409ade98fbd92
#> Description: Averdonk Groessen
#> Public: TRUE
#> Created/Edited: 2020年07月28日T20:18:11Z / 2020年07月28日T20:18:11Z
#> Files: averdonk-groessen.markdown, index.pug, script.js, scripts, style.sass, styles
#> Truncated?: FALSE, FALSE, FALSE, FALSE, FALSE, FALSE

Since a certain date/time

gists(since='2014年05月26日T00:00:00Z', per_page = 2)
#> [[1]]
#> <gist>721a433293af4cb1fb0f66d7ccb37339
#> URL: https://gist.github.com/721a433293af4cb1fb0f66d7ccb37339
#> Description: Atividades 8o Ano
#> Public: TRUE
#> Created/Edited: 2020年07月28日T20:18:22Z / 2020年07月28日T20:18:23Z
#> Files: 8o_ano.md
#> Truncated?: FALSE
#> 
#> [[2]]
#> <gist>d1064ad4f7fa9cd30b4409ade98fbd92
#> URL: https://gist.github.com/d1064ad4f7fa9cd30b4409ade98fbd92
#> Description: Averdonk Groessen
#> Public: TRUE
#> Created/Edited: 2020年07月28日T20:18:11Z / 2020年07月28日T20:18:11Z
#> Files: averdonk-groessen.markdown, index.pug, script.js, scripts, style.sass, styles
#> Truncated?: FALSE, FALSE, FALSE, FALSE, FALSE, FALSE

Request different types of gists, one of public, minepublic, mineall, or starred.

gists('minepublic', per_page = 2)
#> [[1]]
#> <gist>792675323dea1961ce038b2e051d66d4
#> URL: https://gist.github.com/792675323dea1961ce038b2e051d66d4
#> Description: 
#> Public: TRUE
#> Created/Edited: 2020年07月28日T20:17:34Z / 2020年07月28日T20:17:42Z
#> Files: code.R
#> Truncated?: FALSE
#> 
#> [[2]]
#> <gist>98badbaf7334a8a5707418543e178901
#> URL: https://gist.github.com/98badbaf7334a8a5707418543e178901
#> Description: a new cool gist
#> Public: TRUE
#> Created/Edited: 2020年07月28日T20:17:33Z / 2020年07月28日T20:17:33Z
#> Files: stuff.md
#> Truncated?: FALSE

List a single commit

gist(id = 'f1403260eb92f5dfa7e1')
#> <gist>f1403260eb92f5dfa7e1
#> URL: https://gist.github.com/f1403260eb92f5dfa7e1
#> Description: Querying bitly from R 
#> Public: TRUE
#> Created/Edited: 2014年10月15日T20:40:12Z / 2015年08月29日T14:07:43Z
#> Files: bitly_r.md
#> Truncated?: FALSE

Create gist

You can pass in files

file <-system.file("examples", "stuff.md", package = "gistr")
gist_create(file, description='a new cool gist', browse = FALSE)
#> <gist>f7aa5e70e2fb40f4d92e972bcfa6224f
#> URL: https://gist.github.com/f7aa5e70e2fb40f4d92e972bcfa6224f
#> Description: a new cool gist
#> Public: TRUE
#> Created/Edited: 2020年07月28日T20:18:27Z / 2020年07月28日T20:18:27Z
#> Files: stuff.md
#> Truncated?: FALSE

Or, wrap gist_create() around some code in your R session/IDE, with just the function name, and a {' at the start and a }' at the end.

gist_create(code={'
x <- letters
numbers <- runif(8)
numbers

[1] 0.3229318 0.5933054 0.7778408 0.3898947 0.1309717 0.7501378 0.3206379 0.3379005
'})

gist_create(code={'
x <- letters
numbers <- runif(8)
numbers

[1] 0.3229318 0.5933054 0.7778408 0.3898947 0.1309717 0.7501378 0.3206379 0.3379005
'}, browse=FALSE)
#> <gist>394103ff248f2be67bbccce863a89ca7
#> URL: https://gist.github.com/394103ff248f2be67bbccce863a89ca7
#> Description: 
#> Public: TRUE
#> Created/Edited: 2020年07月28日T20:18:29Z / 2020年07月28日T20:18:29Z
#> Files: code.R
#> Truncated?: FALSE

knit and create

You can also knit an input file before posting as a gist:

file <-system.file("examples", "stuff.Rmd", package = "gistr")
gist_create(file, description='a new cool gist', knit=TRUE)
#> <gist>4162b9c53479fbc298db
#> URL: https://gist.github.com/4162b9c53479fbc298db
#> Description: a new cool gist
#> Public: TRUE
#> Created/Edited: 2014年10月27日T16:07:31Z / 2014年10月27日T16:07:31Z
#> Files: stuff.md
#> Truncated?: FALSE

Or code blocks before (note that code blocks without knitr block demarcations will result in unexecuted code):

gist_create(code={'
x <- letters
(numbers <- runif(8))
'}, knit=TRUE)
#> <gist>ec45c396dee4aa492139
#> URL: https://gist.github.com/ec45c396dee4aa492139
#> Description:
#> Public: TRUE
#> Created/Edited: 2014年10月27日T16:09:09Z / 2014年10月27日T16:09:09Z
#> Files: file81720d1ceff.md
#> Truncated?: FALSE

knit code from file path, code block, or gist file

knit a local file

file <-system.file("examples", "stuff.Rmd", package = "gistr")
run(file, knitopts = list(quiet=TRUE)) %>%gist_create(browse = FALSE)
#> <gist>ceeddf11ebf775a1fe465f6791e15323
#> URL: https://gist.github.com/ceeddf11ebf775a1fe465f6791e15323
#> Description: 
#> Public: TRUE
#> Created/Edited: 2020年07月28日T20:18:31Z / 2020年07月28日T20:18:31Z
#> Files: stuff.md
#> Truncated?: FALSE

knit a code block (knitr code block notation missing, do add that in) (result not shown)

run({'
x <- letters
(numbers <- runif(8))
'}) %>%gist_create

knit a file from a gist, has to get file first (result not shown)

gists('minepublic')[[1]] %>%run() %>%update()

working with images

The GitHub API doesn’t let you upload binary files (e.g., images) via their HTTP API, which we use in gistr. There is a workaround.

If you are using .Rmd or .Rnw files, you can set imgur_inject = TRUE in gistr_create() so that imgur knit options are injected at the top of your file so that images will be uploaded to imgur. Alternatively, you can do this yourself, setting knit options to use imgur.

A file already using imgur

file <-system.file("examples", "plots_imgur.Rmd", package = "gistr")
gist_create(file, knit=TRUE)
#> <gist>1a6e7f7d6ddb739fce0b
#> URL: https://gist.github.com/1a6e7f7d6ddb739fce0b
#> Description:
#> Public: TRUE
#> Created/Edited: 2015年03月19日T00:20:48Z / 2015年03月19日T00:20:48Z
#> Files: plots_imgur.md

A file NOT already using imgur

file <-system.file("examples", "plots.Rmd", package = "gistr")
gist_create(file, knit=TRUE, imgur_inject = TRUE)
#> <gist>ec9987ad245bbc668c72
#> URL: https://gist.github.com/ec9987ad245bbc668c72
#> Description:
#> Public: TRUE
#> Created/Edited: 2015年03月19日T00:21:13Z / 2015年03月19日T00:21:13Z
#> Files: plots.md
#> Truncated?: FALSE

List commits on a gist

gists()[[1]] %>%commits()
#> [[1]]
#> <commit>
#> Version: b640145362bb2272c5f0a06ae2aee3241b8f6f59
#> User: sckott
#> Commited: 2020年07月28日T20:18:28Z
#> Commits [total, additions, deletions]: [5,5,0]

Star a gist

Star

gist('cbb0507082bb18ff7e4b') %>%star()
#> <gist>cbb0507082bb18ff7e4b
#> URL: https://gist.github.com/cbb0507082bb18ff7e4b
#> Description: This is my technical interview cheat sheet. Feel free to fork it or do whatever you want with it. PLEASE let me know if there are any errors or if anything crucial is missing. I will add more links soon.
#> Public: TRUE
#> Created/Edited: 2014年05月02日T19:43:13Z / 2018年04月16日T21:11:53Z
#> Files: The Technical Interview Cheat Sheet.md
#> Truncated?: FALSE

Unstar

gist('cbb0507082bb18ff7e4b') %>%unstar()
#> <gist>cbb0507082bb18ff7e4b
#> URL: https://gist.github.com/cbb0507082bb18ff7e4b
#> Description: This is my technical interview cheat sheet. Feel free to fork it or do whatever you want with it. PLEASE let me know if there are any errors or if anything crucial is missing. I will add more links soon.
#> Public: TRUE
#> Created/Edited: 2014年05月02日T19:43:13Z / 2018年04月16日T21:27:36Z
#> Files: The Technical Interview Cheat Sheet.md
#> Truncated?: FALSE

Edit a gist

Add files

file <-system.file("examples", "alm.md", package = "gistr")
gists(what = "minepublic")[[1]] %>%
add_files(file) %>%
update()
#> <gist>394103ff248f2be67bbccce863a89ca7
#> URL: https://gist.github.com/394103ff248f2be67bbccce863a89ca7
#> Description: 
#> Public: TRUE
#> Created/Edited: 2020年07月28日T20:18:29Z / 2020年07月28日T20:18:34Z
#> Files: alm.md, code.R
#> Truncated?: FALSE, FALSE

Delete files

file <-system.file("examples", "alm.md", package = "gistr")
gists(what = "minepublic")[[1]] %>%
delete_files(file) %>%
update()
#> <gist>394103ff248f2be67bbccce863a89ca7
#> URL: https://gist.github.com/394103ff248f2be67bbccce863a89ca7
#> Description: 
#> Public: TRUE
#> Created/Edited: 2020年07月28日T20:18:29Z / 2020年07月28日T20:18:36Z
#> Files: code.R
#> Truncated?: FALSE

Open a gist in your default browser

gists()[[1]] %>%browse()

Opens the gist in your default browser

Get embed script

gists()[[1]] %>%embed()
#> [1] "<script src=\"https://gist.github.com/anupamgogoi-wso2/9230e4ade0074320ec95992ba2fbf518.js\"></script>"

List forks

Returns a list of gist objects, just like gists()

gist(id='1642874') %>%forks(per_page=2)
#> [[1]]
#> <gist>1642989
#> URL: https://gist.github.com/1642989
#> Description: Spline Transition
#> Public: TRUE
#> Created/Edited: 2012年01月19日T21:45:20Z / 2019年10月23日T20:09:07Z
#> Files: 
#> Truncated?: 
#> 
#> [[2]]
#> <gist>1643051
#> URL: https://gist.github.com/1643051
#> Description: Line Transition (Broken)
#> Public: TRUE
#> Created/Edited: 2012年01月19日T21:51:30Z / 2019年10月23日T20:08:44Z
#> Files: 
#> Truncated?:

Fork a gist

Returns a gist object

g <-gists()
(forked <-g[[ sample(seq_along(g), 1) ]] %>%fork())
#> <gist>72a9327aac0cab09900b04a027069ae5
#> URL: https://gist.github.com/72a9327aac0cab09900b04a027069ae5
#> Description: Rimworld output log published using HugsLib
#> Public: TRUE
#> Created/Edited: 2020年07月28日T20:18:43Z / 2020年07月28日T20:18:43Z
#> Files: output_log.txt
#> Truncated?: FALSE

Example use cases

Round-trip storage of a data frame

Maybe you want to use a gist to share some data as an alternative to dput? We can do this by writing our data.frame to a temporary buffer and passing it to gist_create. We can read the data back from the gist by passing its content to read.csv.

data(iris)

str <- ''
tc <-textConnection('str', 'w', local = TRUE)
write.csv(iris, file = tc, row.names = FALSE)
close(tc)

content <-list(content=paste(as.character(str), collapse='\n'))

gistr::gist_create(code = {
 content$content
}, description = "using a gist as a data store", 
filename = "iris.csv")
#> <gist>c7dfe593f4944df4818df884689734f9
#> URL: https://gist.github.com/c7dfe593f4944df4818df884689734f9
#> Description: using a gist as a data store
#> Public: TRUE
#> Created/Edited: 2019年07月18日T14:23:23Z / 2019年07月18日T14:23:23Z
#> Files: iris.csv
#> Truncated?: FALSE

output <-read.csv(
 text = gist(gists(what = "minepublic", per_page = 1)[[1]]$id)$
files$iris.csv$content)

identical(output, iris)
#> TRUE