---
title: "rperseus Vignette"
author: "David Ranzolin"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Vignette Title}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

### Introduction

`rperseus` provides tools to get and analyze classical texts. Version 0.1.2 includes:

* `get_perseus_text`, a function to obtain a text from the Perseus Digital Library
* `perseus_parallel`, a function to render a text parallel in `ggplot2`
* `parse_excerpt`, a function to parse any Greek excerpt
* `perseus_catalog`, a data frame of available texts
* `greek_stop_words`, a data frame of Greek pronouns, articles, prepositions, and particles

```{r}
library(rperseus)
head(perseus_catalog)
```

A snapshot of available authors:

```{r warning=FALSE, message=FALSE}
library(dplyr)
count(perseus_catalog, group_name, sort = TRUE)
```

### Getting a Text

Once you've identified the relevant URN, paste it into a call to `get_perseus_text`. Here I've called for the Greek text of Plato's *Crito*:

```{r}
crito <- get_perseus_text(urn = "urn:cts:greekLit:tlg0059.tlg003.perseus-grc2")
crito$text[1]
```

### Getting Multiple Texts with the tidyverse

You can collect all of Plato's available English translations with the `tidyverse:`

```{r eval = FALSE}
plato <- perseus_catalog %>% 
  filter(group_name == "Plato",
         language == "eng") %>% 
  pull(urn) %>% 
  map_df(get_perseus_text)
```

### Rendering Parallels

You can render small parallels with `perseus_parallel`:

```{r,fig.width=8, fig.height=6}
tibble::tibble(label = c("Colossians", "1 Thessalonians", "Romans"),
              excerpt = c("1.4", "1.3", "8.35-8.39")) %>%
    dplyr::left_join(perseus_catalog) %>%
    dplyr::filter(language == "grc") %>%
    dplyr::select(urn, excerpt) %>%
    as.list() %>%
    purrr::pmap_df(get_perseus_text) %>%
    perseus_parallel(words_per_row = 4)
```

### Parsing Excerpts

You can parse any Greek excerpt with `parse_excerpt`. A data frame is returned including part of speech, person, number, tense, mood, voice, gender, case, and degree.

```{r}
parse_excerpt("urn:cts:greekLit:tlg0031.tlg002.perseus-grc2", "5.1-5.3")
```