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

```{r, include = FALSE}
# Preview vignette with: devtools::build_rmd("vignettes/palettes.Rmd")
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The goal of palettes is to provide methods for working with colour palettes for users and developers.

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

## Creating

`pal_colour()` is a nice way to create a colour vector. Colours can be a character vector of hexadecimal strings of the form `"#RRGGBB"` or `"#RRGGBBAA"`, colour names from `grDevices::colors()`, or a positive integer that indexes into `grDevices::palette()`. By default, colour vectors are always printed as hex codes with colour previews.

```{r}
colour_vector <- pal_colour(
  c("#a00e00", "#d04e00", "#f6c200", "#0086a8", "#132b69")
)

colour_vector
```

`pal_palette()` is a nice way to create named colour palettes.

```{r}
colour_palette <- pal_palette(
  egypt = c("#dd5129", "#0f7ba2", "#43b284", "#fab255"),
  java  = c("#663171", "#cf3a36", "#ea7428", "#e2998a", "#0c7156")
)

colour_palette
```

## Casting and coercion

To compliment `pal_colour()`, palettes provides `as_colour()` to cast objects into colour vectors.

```{r}
colour_strings <- c("orange", "purple")
as_colour(colour_strings)
```

To compliment `pal_palette()`, palettes provides `as_palette()` to cast objects into colour palettes.

```{r}
colour_list <- list(OrPu = c("orange", "purple"))
as_palette(colour_list)
```

Colour vectors and colour palettes can also be coerced into a tibble with `as_tibble()`. See `vignette("tibble", package = "tibble")` for an overview of tibbles.

```{r}
as_tibble(colour_vector)

as_tibble(colour_palette)
```

<!-- TODO: add coercion examples -->

## Subsetting

Colour vectors can be subset using `[`.

  - To extract one or more colours use positive integers:

    ```{r}
    colour_vector[3]
    ```
  
  - To drop one or more colours use negative integers:

    ```{r}
    colour_vector[-3]
    ```
    
  - To move one or more colours extract, drop, and combine:

    ```{r}
    c(colour_vector[-3], colour_vector[3])
    ```

Colour palettes can be subset using `[`, `[[`, and `$`.

  - To extract one or more colour palettes use `[`:

    ```{r}
    colour_palette["egypt"]
    ```
  
  - To extract a single colour palette as a colour vector use `[[` or `$`:

    ```{r}
    colour_palette[["egypt"]]
    
    colour_palette$egypt
    ```
    
  - To get names of colour palettes use `names()`:

    ```{r}
    names(colour_palette)
    ```

<!--
## Mixing

Colour vectors can be mixed to create new colours.

  - To mix colours in an additive space use `+`:

    ```{r}
    pal_colour("red") + pal_colour("blue")
    ```
    
  - Subtractive mixing with `-` will be supported in a future version.
-->

## Plotting

`plot()` is a nice way to showcase colour vectors and colour palettes. The appearance of the plot depends on the input.

  - Colour vectors are plotted as swatches:

    ```{r}
    plot(colour_vector)
    ```
  
  - Single colour palettes are plotted as swatches with a palette name overlay:

    ```{r}
    plot(colour_palette["egypt"])
    ```
    
  - Multiple colour palettes are plotted as faceted swatches with palette name titles:

    ```{r}
    plot(colour_palette)
    ```

To interpolate or change the direction of colours in a plot, use the optional `n`, `direction`, `space`, or `interpolate` arguments.

```{r}
plot(colour_vector, n = 7, direction = -1, interpolate = "linear")
```

All plots are ggplot2 objects and can be customized using any of the standard ggplot2 methods. See the ggplot2 [customizing FAQ](https://ggplot2.tidyverse.org/articles/faq-customising.html) for some common examples.

## Printing

```{r, include=FALSE}
op <- options()
```

The printing behaviour of colour vectors can be adjusted using a variety of global options. See `help("palettes-options")` for a list of all the available options and their default values.

For example, to change the symbol used for colour previews, set the `palettes.print_symbol` option.

```{r}
options(palettes.print_symbol = "square")
colour_vector
```

```{r, include=FALSE}
options(op)
```

Set multiple options together for unique printing styles.
    
  - Print colour vectors compactly:

    ```{r}
    options(
      palettes.print_symbol = "circle_large",
      palettes.print_hex = FALSE,
      palettes.print_width = 5
    )
    colour_palette
    ```
    
    ```{r, include=FALSE}
    options(op)
    ```
    
  - Mimic the appearance of a character vector:

    ```{r}
    options(
      palettes.print_symbol = FALSE,
      palettes.print_sep = ", ",
      palettes.print_width = 5,
      palettes.print_index = TRUE
    )
    colour_vector
    ```
    
    ```{r, include=FALSE}
    options(op)
    ```

Set any of these options in your [`.Rprofile`](https://rstats.wtf/r-startup.html#rprofile) dotfile to have them persist across R sessions on a global or per-project basis.