---
title: "Intro to rhymer"
author: "Noah Landesberg"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Intro to rhymer}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

Welcome to `rhymer`, an R package for getting rhyming and other related words through the Datamuse API. I highly recommend reading through the [Datamuse API website](https://www.datamuse.com/api/) before getting started.

## Main functions
`rhymer` has 4 main functions that allow you to get data on related words through the Datamuse API.    
  
They are: 

  - `get_rhyme()` - a function to get rhyming words.  
  - `get_means_like()` - a function to get words with similar meaning.  
  - `get_sounds_like()` - a function to get words that sound similar.  
  - `get_spelled_like()` - a function to get words that are spelled similarly.  

There is also a more flexible function `get_other_related()` that allows you to use the API to get data on other related words using a series of 'codes' described on the [Datamuse API website](https://www.datamuse.com/api/).  

Each function is default limited to return a maximum of 10 results, but can return more. Functions also default to return a dataframe with a row for each word, and an associated score. Different functions will return slightly different additional columns if returning a dataframe.

```{r}
library(rhymer)
```
  
### `get_rhyme()`

This function was the initial inspiration behind this package. It makes the work of finding rhyming words easy. In the background, it is referencing the [CMU Pronouncing Dictionary](https://en.wikipedia.org/wiki/CMU_Pronouncing_Dictionary). At it's simplest, you can pass in a word and `get_rhyme()` will return a dataframe of rhyming words. For example:

```{r}
get_rhyme("test")
```

The function has some additional arguments that you can use to specify the rhyme. 

You can specify the number of syllables returned using `num_syl`:
```{r}
get_rhyme("test", num_syl = 2)
```

You can specify the type of data returned using `return_type`:
```{r}
# "df" returns a single dataframe (which is the default behavior).
get_rhyme("test", return_type = "df")

# "word" returns the type rhyme in the form of a single word vector.
get_rhyme("test", return_type = "word")

# "random_word" or "rand" returns a single, random word.
get_rhyme("test", return_type = "random_word")
 
# "vector" returns a vector of words.
get_rhyme("test", return_type = "vector")
```

You can also specify the number of words returned (defaults to 10 so as to not kill the API) using `limit`:
```{r}
get_rhyme("test", limit = 5)
```
  
### `get_means_like()`

In the background, this function works by referencing [WordNet](https://wordnet.princeton.edu) and other online dictionaries. It has the same arguments as `get_rhyme()` for limiting the number of results (`limit`) and for what data structure to return (`return_type`). It also returns additional information about the part of speech returned.

```{r}
get_means_like("test")
```
  
### `get_sounds_like()`

In the background, this function works by referencing referencing the [CMU Pronouncing Dictionary](https://en.wikipedia.org/wiki/CMU_Pronouncing_Dictionary). It has the same arguments as `get_rhyme()` for limiting the number of results (`limit`), for what data structure to return (`return_type`), and for the number of syllables to limit to (`num_syl`).

```{r}
get_sounds_like("test", num_syl = 2)
```
  
### `get_spelled_like()`

This function has the same arguments as `get_rhyme()` for limiting the number of results (`limit`) and for what data structure to return (`return_type`). 
```{r}
get_spelled_like("test")
```