---
title: "Introduction to cowsay"
author: "Scott Chamberlain, Tyler Rinker, Thomas Leeper, Noam Ross, Rich FitzJohn, Kiyoko Gotanda, Carson Sievert, Andy Teucher, Karl Broman, Franz-Sebastian Krah, Lucy D'Agostino McGowan, Guangchuang Yu, Paolo Sonego, and Philipp Boersch-Supan"
date: "`r Sys.Date()`"
output:
  html_document:
    toc: true
    toc_float: true
    theme: readable
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{cowsay tutorial}
  %\VignetteEncoding{UTF-8}
---

```{r echo=FALSE}
has_multicolor <- requireNamespace("multicolor", quietly = TRUE)
knitr::opts_chunk$set(
  comment = "#>",
  collapse = TRUE
)
```

`cowsay` makes it easy to print messages, warnings, or character strings with various animals and other creatures.

## Installation

Stable version from CRAN

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

or dev version from GitHub

```{r eval=FALSE}
remotes::install_github("sckott/cowsay")
```

```{r}
library(cowsay)
```

## The animals

The animals, and other ascii creatures, are all in a single named character vector that is exported from the package. Thus, you can access each animal yourself, and do whatever you want with it. 

As of this writing, there are `r length(animals)` animals.

The names of the animals:

```{r}
sort(names(animals))
```

For example, access the cow

```{r}
cow <- animals[['cow']]
cat(cow)
```

## Say something

We expose the function `say()` in this package, which you can use to envoke any animal in the package, and make it say whatever you want. Some examples:

```{r}
say("why did the chicken cross the road", "chicken")
```

```{r}
say("boo!", "ghost")
```

```{r}
say("nope, don't do that", type = "warning")
```

There's the special `time`, that will print out the time

```{r}
say('time')
```

## It's how you say it

You can use `say()` and give back a string, message, or warning

Message

```{r}
say("hello world", by = "cow")
```

Warning

```{r}
say("hello world", by = "cow", type = "warning")
```

String

```{r}
say("hello world", by = "cow", type = "string")
```


## Add color

```{r eval = has_multicolor}
library(jsonlite)
library(multicolor)
```


We rely on the [`crayon`](https://github.com/r-lib/crayon) package for color and the [`multicolor`](https://github.com/aedobbyn/multicolor) package for multiple colors. The arguments you supply to `what_color` and `by_color` can be strings -- either the color name or a hex value -- or a [function of class `crayon`](https://github.com/r-lib/crayon#styles).


```{r eval = has_multicolor}
say(what = "fortune",
    by = "rabbit",
    what_color = "#FF4500",
    by_color = "red")
```


`colors()` are all supported as are any `rgb` values that evaluate to a string. Supplying multiple colors for `what_color` or `by_color` is allowed, as long as they're in a character vector. "rainbow" is also allowed.

```{r eval = has_multicolor}
# make a vector of animals safe to use on windows in case vignette built on windows
not_on_windows <- c('shortcat','longcat','fish','signbunny','stretchycat',
  'anxiouscat','longtailcat','grumpycat','mushroom')
names_safe <- names(animals)[!names(animals) %in% not_on_windows]
```

```{r eval = has_multicolor}
say(what = "fortune", 
    by = sample(names_safe, 1),
    what_color = rgb(.1, .2, .3),
    by_color = sample(colors(), 5),
    type = "message")
```


```{r eval = has_multicolor}
say(what = "fortune", 
    by = sample(names_safe, 1),
    what_color = rgb(.1, .2, .3),
    by_color = sample(colors(), 5),
    type = "message")
```

`"rainbow"` is the same as `c("red", "orange", "yellow", "green", "blue", "purple")`. Saves you a bit of typing.

```{r eval = has_multicolor}
say(what = "foobar",
    by = "shark",
    what_color = "rainbow",
    by_color = c("rainbow", "rainbow", "rainbow"))
```

The main advantage of using `crayon` functions instead of color strings is the ability to combine styles together.

```{r eval = has_multicolor}
library(crayon)

say(what = "fortune",
    by = "egret",
    what_color = bgBlue$white$italic,
    by_color = bold$green)
```