<!--
%\VignetteEngine{knitr::knitr}
%\VignetteIndexEntry{gistr vignette}
%\VignetteEncoding{UTF-8}
-->

```{r, eval=TRUE, echo=FALSE}
knitr::opts_chunk$set(
	message = FALSE,
	warning = FALSE,
	comment = "#>"
)
```

gistr tutorial
============

## Install

Stable version from CRAN

```{r eval=FALSE}
install.packages("gistr")
```

Development version from GitHub

```{r eval=FALSE}
devtools::install_github("ropensci/gistr")
```

```{r}
library("gistr")
```

## Authentication

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

* Generate a personal access token (PAT) at [https://help.github.com/articles/creating-an-access-token-for-command-line-use](https://help.github.com/articles/creating-an-access-token-for-command-line-use) and record it in the `GITHUB_PAT` envar.
* Interactively login into your GitHub account and authorise with OAuth.

Using the PAT is recommended.

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

```{r eval=FALSE}
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 wofklow (with some explanation):

```{r eval=FALSE}
file <- system.file("examples", "stuff.Rmd", package = "gistr")
gists(what = "minepublic")[[1]] %>% # List my public gists, and index 1st
  add_files(file) %>% # Add new file to that gist
  update() # update sends a PATCH command to Gists API to add file to your gist
```

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

```{r eval=FALSE}
file <- system.file("examples", "example1.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)

```{r eval=FALSE}
update(add_files(gists(what = "minepublic")[[1]], file))
```

## Rate limit information

```{r}
rate_limit()
```


## List gists

Limiting to a few results here to keep it brief

```{r}
gists(per_page = 2)
```

Since a certain date/time

```{r}
gists(since = '2014-05-26T00:00:00Z', per_page = 2)
```

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

```{r}
gists('minepublic', per_page = 2)
```


## List a single gist

```{r}
gist(id = 'f1403260eb92f5dfa7e1')
```

## Create gist

You can pass in files

First, get a file to work with

```{r}
stuffpath <- system.file("examples", "stuff.md", package = "gistr")
```

```{r eval=FALSE}
gist_create(files = stuffpath, description = 'a new cool gist')
```

```{r}
gist_create(files = stuffpath, description = 'a new cool gist', browse = FALSE)
```

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

```{r}
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)
```

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

```{r eval=FALSE}
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-27T16:07:31Z / 2014-10-27T16:07:31Z
#>   Files: stuff.md
```

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

```{r eval=FALSE}
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-27T16:09:09Z / 2014-10-27T16:09:09Z
#>   Files: file81720d1ceff.md
```

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

knit a local file

```{r}
file <- system.file("examples", "stuff.Rmd", package = "gistr")
run(file, knitopts = list(quiet = TRUE)) %>% gist_create(browse = FALSE)
```

```{r echo=FALSE}
gists('minepublic')[[1]] %>% delete
```

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

```{r eval=FALSE}
run({'
x <- letters
(numbers <- runif(8))
'}) %>% gist_create()
```

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

```{r eval=FALSE}
gists('minepublic')[[1]] %>% run() %>% update()
```

## List commits on a gist

```{r}
gists()[[1]] %>% commits()
```

## Star a gist

Star

```{r}
gist('b564093d359eb735138a97258d03f333') %>% star()
```

Unstar

```{r}
gist('b564093d359eb735138a97258d03f333') %>% unstar()
```

## Update a gist

Add files

First, path to file

```{r}
file <- system.file("examples", "alm.md", package = "gistr")
```

```{r}
gists(what = "minepublic")[[1]] %>%
  add_files(file) %>%
  update()
```

Delete files

```{r}
gists(what = "minepublic")[[1]] %>% 
  delete_files(file) %>%
  update()
```

## Open a gist in your default browser

```{r eval=FALSE}
gists()[[1]] %>% browse()
```

> Opens the gist in your default browser

## Get embed script

```{r}
gists()[[1]] %>% embed()
```

### List forks

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

```{r}
gist(id = '1642874') %>% forks(per_page = 2)
```

## Fork a gist

Returns a `gist` object

```{r}
g <- gists()
(forked <- g[[ sample(seq_along(g), 1) ]] %>% fork())
```

```{r echo=FALSE}
gist(forked$id) %>% delete()
```

## Example use cases

_Working with the Mapzen Pelias geocoding API_

The API is described at [https://github.com/pelias/pelias](https://github.com/pelias/pelias), and is still in alpha they say. The steps: get data, make a gist. The data is returned from Mapzen as geojson, so all we have to do is literally push it up to GitHub gists and we're done b/c GitHub renders the map.

```{r eval=FALSE}
library('httr')
base <- "http://pelias.mapzen.com/search"
res <- httr::GET(base, query = list(input = 'coffee shop', lat = 45.5, lon = -122.6))
json <- httr::content(res, "text")
gist_create(code = json, filename = "pelias_test.geojson")
#> <gist>017214637bcfeb198070
#>   URL: https://gist.github.com/017214637bcfeb198070
#>   Description:
#>   Public: TRUE
#>   Created/Edited: 2014-10-28T14:42:36Z / 2014-10-28T14:42:36Z
#>   Files: pelias_test.geojson
```

And here's that gist: [https://gist.github.com/sckott/017214637bcfeb198070](https://gist.github.com/sckott/017214637bcfeb198070)

![](img/gistr_ss.png)

_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`.

```{r eval=FALSE}
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-18T14:23:23Z / 2019-07-18T14: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
```
