---
title: "flashr"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{flashr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

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

Flashcards are a great way to learn information. The repetition of exposure to technical terms and their descriptions/definitions helps with remembering those relationships (Yüksel et al., 2020)^[Yüksel, H. G., Mercanoğlu, H. G., & Yılmaz, M. B. (2020). Digital flashcards vs. Wordlists for learning technical vocabulary. Computer Assisted Language Learning, 0(0), 1–17. <https://doi.org/10.1080/09588221.2020.1854312>]. Hermans (2021)^[Hermans, F. (2021). The Programmer’s Brain. Manning. <https://www.manning.com/books/the-programmers-brain>] suggests using flashcards for learning programming languages, which inspired the `{flashr}` package. The aim of this package is to create a simple way to use and generate new decks of flashcards for learning R function or anything else you want to learn!

## Usage
`{flashr}` has a number of [built-in flashcard decks](https://github.com/JeffreyRStevens/flashr_decks) to help you learn R, and especially the [tidyverse](https://www.tidyverse.org/). The workhorse of the package is the [`flashcard()`](https://jeffreyrstevens.github.io/flashr/reference/flashcard.html) function, which uses [reveal.js](https://revealjs.com/)^[Via the [revealjs](https://github.com/rstudio/revealjs) R package.] to generate an HTML presentation displaying terms and descriptions. For RStudio users, the flashcard presentation will appear in the Viewer pane. Outside of RStudio, the function will open the presentation in your default browser. In either case, you can advance slides with the right arrow key or by clicking the right arrow in the presentation.

For example, to create a set of flashcards from the built-in `data_types` deck, simply run:
```{r eval = FALSE}
flashcard("data_types")
```
The presentation will start with the title of the deck, then give a blank slide, then present the first term, followed by the description, and a blank slide. The order of terms/descriptions is randomized when the [`flashcard()`](https://jeffreyrstevens.github.io/flashr/reference/flashcard.html) function is run, so just re-run it to generate a different order.

### Guess the term
By default, terms are presented before descriptions. So when you see a term, you should try to define/describe the term. But it is possible to present descriptions first so you can guess the term by including the `termfirst = FALSE` argument.
```{r eval = FALSE}
flashcard("data_types", termsfirst = FALSE)
```

### Including package names
Another feature of [`flashcard()`](https://jeffreyrstevens.github.io/flashr/reference/flashcard.html) is that it can present the name of the package for each function. Often this is useful to distinguish base R function from functions that require other packages. By default, presentations include the package names. However, you can turn this off with `package = FALSE`.

```{r eval = FALSE}
flashcard("data_types", package = FALSE)
```

### Themes
Because `{flashr}` uses reveal.js to create the presentations, it can use the available [reveal.js themes](https://revealjs.com/themes/). By default, [`flashcard()`](https://jeffreyrstevens.github.io/flashr/reference/flashcard.html) uses the `moon` theme, but if that doesn't suit you, you can change the theme by setting the `theme` argument. At the moment, available themes are `black`, `white`, `league`, `beige`, `sky`, `night`, `serif`, `simple`, `solarized`, `blood`, and `moon`.
```{r eval = FALSE}
flashcard("data_types", theme = "sky")
```

## Available decks
Currently, `{flashr}` includes a few example decks (`data_types`, `vectors`) and decks of functions and arguments derived from [R for Data Science (first edition)](https://r4ds.had.co.nz/). These decks are housed at the [flashr_decks GitHub repo](https://github.com/JeffreyRStevens/flashr_decks), and more are on the way.

To see what decks are available, use [`list_decks()`](https://jeffreyrstevens.github.io/flashr/reference/list_decks.html):
```{r}
list_decks()
```

Note that the list of decks includes the deck names in parenthesis next to the descriptions. For instance, for _R4DS Chapter 3_, the name is `r4ds3`.

This function includes pattern matching. So if you want to narrow you list down, add a search string.
```{r}
list_decks(pattern = "r4ds")
```

If you want to list the decks and then choose one, use [`choose_deck()`](https://jeffreyrstevens.github.io/flashr/reference/choose_deck.html):
```{r eval = FALSE}
choose_deck("r4ds")
```

```{r echo = FALSE}
decks <- list_decks("r4ds")
cli::cli_text("Please enter the number for a deck or 0 to exit: ")
```

Or, if you already know the deck number that you want, you can include it in the `choice` argument.

```{r eval = FALSE}
choose_deck("r4ds", choice = 2)
```

Of course, a faster way to do this is to enter the deck name directly into [`flashcard()`](https://jeffreyrstevens.github.io/flashr/reference/flashcard.html). 
```{r eval = FALSE}
flashcard("r4ds3")
```

You can also view [examples of all of the decks in HTML](https://jeffreyrstevens.github.io/flashr_decks/decks.html).

## Creating your own decks

In addition to built-in decks, you can create your own decks by making a data frame or CSV file with the terms and descriptions or passing a vector of functions from the [flashr_decks list of functions](https://jeffreyrstevens.github.io/flashr_decks/functions.html). 

### Data frame or CSV file

Simply create a data frame or CSV file that includes a column labeled `term` and a column labeled `description`. You can also include a `package` column listing package names and a `title` column to give your presentation a title, but these are optional arguments^[Note `title` is required when submitting to [flashr_decks](https://github.com/JeffreyRStevens/flashr_decks)]. Here is an example of a CSV file with all of the columns.

```{r}
my_deck <- read.csv("../inst/extdata/operators.csv")
knitr::kable(my_deck)
```

You can, of course, store those decks on your local computer to use them. But if your decks may be useful for other people (for example, based on books or publicly available resources), consider submitting them to the [flashr_decks repo](https://github.com/JeffreyRStevens/flashr_decks/).

Alternatively, you can create your own repo of decks and specify with the `repo` argument. Just make sure that your CSV files are saved in a `decks/` folder in your repo's root directory.
```{r}
list_decks(repo = "JeffreyRStevens/flashr_decks")
```

### Drawing from list of functions

We've collected all of the functions in the currently available decks in a [table at the flashr_decks repo](https://jeffreyrstevens.github.io/flashr_decks/functions.html). The [`create_deck()`](https://jeffreyrstevens.github.io/flashr/reference/create_deck.html) function takes a vector that you create of functions from the [function list](https://jeffreyrstevens.github.io/flashr_decks/functions.html). Make sure to include the `()` at the end of the function name (except for operators)! And don't forget to include a title.

```{r eval = FALSE}
my_functions <- c("%>%", "ggplot()", "aes()", "geom_point()")
create_deck(my_functions,
  title = "ggplot basics"
)
```

All of the arguments from [`flashcard()`](https://jeffreyrstevens.github.io/flashr/reference/flashcard.html) apply to [`create_deck()`](https://jeffreyrstevens.github.io/flashr/reference/create_deck.html), so you can customize the theme, fonts, etc. and save the output locally.

### Extracting functions from R Markdown and Quarto files

If you want to extract functions from existing R Markdown or Quarto files, you can use `build_functions_df()`. Just pass it either a file path or a URL for an R Markdown or Quarto file, and it will extract those functions and create a data frame that can be passed to `flashcard()` to create a deck. However, to include descriptions, you will either need to pull them from the [table at the flashr_decks repo](https://jeffreyrstevens.github.io/flashr_decks/functions.html) by setting `desc = TRUE` (the default option) or edit the data frame by hand either directly in R or by writing to a CSV, editing the CSV, and importing it again. If there are functions you'd like to see added to the flashr_decks table, [let me know](mailto:jeffrey.r.stevens@protonmail.com).

Note that the `build_functions_df()` function is built on `extract_code()` and `extract_functions()`, which may be useful in other contexts. Use `extract_code()` to extract the contents of all R code blocks in R Markdown and Quarto documents and `extract_functions()` to extract all R functions found in a character vector.

### Expanding your flashcards

These flashcards were designed to learn programming functions/arguments and their definitions. But `{flashr}` can be use for any pairing of terms and descriptions, computing-based or otherwise. So feel free to make flashcard decks of whatever you want to learn: words from a language that you are learning, terms you're studying for classes, whatever you need!