---
title: "Alternative connections to projects"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Alternative connections to projects}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup}
library(gitlabr)
```

# Creating connections

The recommended way to set a connection once and for all to a specific GitLab instance during your session is to use `set_gitlab_connection()` as specified in the quick start guide vignette.

```{r}
set_gitlab_connection(
  gitlab_url = "https://gitlab.com",
  private_token = Sys.getenv("GITLAB_COM_TOKEN")
)
```

However, if you are looking for connections to multiple GitLab instances in the same session or would like to set different accounts, you can define connections using `gl_connection()`.  

The idea of connections in 'gitlabr' is to generate functions with the same signature and capability as that of the central API call function `gitlab()`, but with certain parameters set to fixed values (["curried"](https://en.wikipedia.org/wiki/Currying)).
This way these more specialized functions represent and provide the connection -- for example -- to a specific GitLab instance as a specific user.
Such specialized functions can be created with the function `gl_connection()` and then used exactly as you would use `gitlab()`:

```{r eval = FALSE}
my_gitlab <- gl_connection("https://gitlab.com",
  private_token = Sys.getenv("GITLAB_COM_TOKEN")
)
my_gitlab("projects")
```

```{r echo = FALSE, eval = FALSE, message=FALSE}
library(dplyr)
my_gitlab("projects") %>%
  filter(public == "TRUE") %>%
  select(name, everything())
```

`gl_connection()` can take arbitrary parameters, returning a function that issues API requests with these parameter values.

Similarly, `gl_project_connection()` can be used as a convenience wrapper to directly connect to a specific project in a GitLab instance. 

## function-in-function style

The recommended way to use 'gitlabr' functions is to directly use `gl_*()` function after setting the `set_gitlab_connection()`.
For instance with `gl_create_issue()`.

```{r}
gl_create_issue(project = "<my-project-id>", title = "Implement new feature")
```


When using custom connections, as for calling the `gitlab()` function, the query is passed through the `req` argument as a vector of characters (e.g. "projects").

```{r}
my_gitlab(req = c("projects", "<my-project-id>", "issues"))
```

Another option is to pass a *function* to the `req` argument that will then be called along with the additional parameters, using the connection for all API calls :

```{r eval = FALSE}
my_gitlab(gl_create_issue, title = "Implement new feature", project = "<my-project-id>")
```

`gl_create_issue()` is an example function here, the principle style works for all convenience functions of 'gitlabr' starting with `gl_*()`.

Some of the convenience functions perform additional transformation or renaming of parameters.
Hence, the parameters given to the exemplary `my_gitlab(...)` call after the function should be valid according to the specified function's documentation, and may differ from names used in the GitLab API itself, although this occurs only very rarely.

## Define a custom function with `gitlab()` and a temporary connection

All API possibilities are not available in 'gitlabr'. You can look at vignette "Go further: understand and build your functions" if you want to build your own API function.  
Using a `gitlab()`, out of the recommended way for connection, requires using the `gitlab_con` parameter as follows.

```{r}
gitlab(
  c("projects", "<my-project-id>", "issues"),
  gitlab_con = gl_connection("https://gitlab.com",
    private_token = Sys.getenv("GITLAB_COM_TOKEN")
  )
)
```