README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

options(pakret.render_mode = FALSE)

make_template <- function(lines, to_render = TRUE) {
  if (to_render) {
    args <- list("%s", "`r pakret:::load_foo()` `r pakret:::load_bar()`")
  } else {
    args <- list("references.bib", "")
  }
  do.call(sprintf, c(lines, args))
}
```

# pakret

<!-- badges: start -->
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![CRAN status](https://www.r-pkg.org/badges/version/pakret)](https://CRAN.R-project.org/package=pakret)
[![R-CMD-check](https://github.com/arnaudgallou/pakret/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/arnaudgallou/pakret/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

## Overview

pakret is a minimalistic R package citation tool to reference and cite R and R packages on the fly in R Markdown and Quarto.

## Installation

Install pakret from CRAN with:

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

Alternatively, you can install the development version of pakret from GitHub with:

```{r, eval = FALSE}
# install.packages("pak")
pak::pak("arnaudgallou/pakret")
```

## Usage

Simply use `pkrt()` whenever you want to cite R or an R package in your document:

````{r, include = FALSE}
template <- pakret:::dedent('
  ---
  bibliography: %s
  ---

  ```{r}
  #| include: false
  library(pakret)
  ```
  %s
  We used `r pkrt("foo")` to extract the data.

  Analyses were performed using `r pkrt("bar")`.

  ## References
')
````

```{r, echo = FALSE, class.output = "default"}
cat(make_template(template, FALSE))
```

pakret handles everything for you.

Here’s the markdown output produced by the document above:

```{r, echo = FALSE}
make_template(template) |>
  pakret:::local_files() |>
  pakret:::read_local_file() |>
  cat()
```

It's also possible to cite a collection of packages with `pkrt_list()`:

````{r, include = FALSE}
template <- pakret:::dedent('
  ---
  bibliography: %s
  ---

  ```{r}
  #| include: false
  library(pakret)
  ```
  %s
  We used the following packages: `r pkrt_list("foo", "bar")`.

  ## References
')
````

```{r, echo = FALSE, class.output = "default"}
cat(make_template(template, FALSE))
```

<!-- separator -->

```{r, echo = FALSE}
make_template(template) |>
  pakret:::local_files() |>
  pakret:::read_local_file() |>
  cat()
```

Unhappy with the default templates? pakret lets you define your own:

````{r, include = FALSE}
template <- pakret:::dedent('
  ---
  bibliography: %s
  ---

  ```{r}
  #| include: false

  library(pakret)
  pkrt_set(pkg = "the R package :pkg (v. :ver; :ref)")
  ```
  %s
  We used `r pkrt("foo")` to analyse the data.

  ## References
')
````

```{r, echo = FALSE, class.output = "default"}
cat(make_template(template, FALSE))
```

<!-- separator -->

```{r, echo = FALSE}
make_template(template) |>
  pakret:::local_files() |>
  pakret:::read_local_file() |>
  cat()
```

Note that by default pakret writes new references into the first `.bib` file specified in the bibliography list.
You can change which `.bib` file to save references to using `pkrt_set()`.