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

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE, comment = "#>", message = FALSE, warning = FALSE, error = FALSE, tidy = TRUE, out.width = "100%"
)
library(tabr)
```

This section covers helper functions related to phrases. These functions assist with improving readability, organization, and limiting the amount of typing required to specify phrases where possible.

## Aliases

Briefly, there are some convenient aliases for `tabr` functions that are used often. These aliases have short function names to help keep the music notation R syntax a more concise if desired. These include:

*    `p`, an alias for `phrase`.
*    `tp`, an alias for `transpose`.

The most common conflicts to watch out for are using `tabr` with `shiny` where `p` is a function and if you use `purrr` to help wrangle some of your more complex tablature, it has its own `transpose` function. Pay attention to package load order and/or use explicit names spaces if working with these packages loaded.
The recommended approach is to stick with `phrase` in apps where users will not see your code anyway and stick with `tp` for transposition in general.

## Duplicate and glue

The previous section on phrases presented an opportunity to introduce `dup` for duplicating or repeating strings and `glue` for joining them together. These were used on strings passed to `phrase` but work on any character string.

To recap, `dup`, short for duplicate, is a simple wrapper around `rep` that maintains the `phrase` class when passed a phrase object and space-delimitation when collapsing the repeated input.  `glue` is a simple wrapper around `paste` that similarly maintains space-delimitation. It can be passed an arbitrary number of input simple character strings or phrase objects. The `phrase` class is applied to the output as long as at least one input passed to `glue` is a phrase object. It is the responsibility of the user to ensure that in such a case a simple character string also represents valid phrase content so that the output phrase is valid.

```{r join}
glue("c3 d3 e3", "f3 g3 a3")
dup("c3 d3 e3", 2)
```

## Rests

The `rest` function is a simple wrapper around `rep` much like `dup`. It is useful when you need to propagate a number of rests, perhaps not all of equal duration. It accepts two vectorized arguments. The first is the duration of the rest. The second is the number of times to repeat it.

For example, say a score has multiple tracks. During a certain period in the score, one track goes silent and needs to be carried over with a sequence of rests. Perhaps the instrument dropped out in the middle of a measure and returns in the middle of another, with several full measures in between.
This can easily be notated using `dup` and `glue`, but it could be more convenient with `rest`, or at least offer more interpretable code if you prefer.

In this example, using `rest` is compared with writing out the full `notes` string as well as using some combinations of `dup` and `glue`. It is a matter of preference which approach you take and dependent on the content being repeated and pasted together.
Note that using the terminal in-string multiplicative expansion operator, `*`, in cases of many adjacent single-element repetitions, is by far the best option as far as shortening code is concerned.
If this method is preferred, it essentially removes any edge case preference there may have been for `rest`.

```{r rest}
"r8 r8 r8 r1 r1 r1 r1 r1 r1 r1 r1 r1 r1 r4."
glue(dup("r8", 3), dup("r1", 10), "r4.")
rest(c(8, 1, "4."), c(3, 10, 1))
"r8*3 r1*10 r4."
```

## Ties

Tied notes were introduced momentarily in the previous section on phrases. The example given showed that ties are denoted by appending the pitch letter of the note with `~` and this will create a tie in the output from this note to the next one.

This can be frustrating to type and to read when done for six-string chords for example. `tie` can make this more bearable. Chords receive further discussion in subsequent sections. They were only shown very briefly at the end of the last section so that space-delimited time and simultaneous notes could be demonstrated clearly. For now, this is enough to appreciate this example of `tie`.

```{r tie}
em <- "e,a,dgbe'"
tie(em)
```

## Hammer on/pull off

There is a simple helper function, `hp`, for hammer ons and pull offs, or for slurs in general. Like several other helpers it is a wrapper around paste. It ensures slurs come in an even number so there is always a starting and stopping point and accepts several input styles.

```{r hp1}
hp("16 16")
hp("16", "16")
hp(16, 16, 8, "2.")
```

It is particularly useful for long runs of similar repeated hammer ons and/or pull offs that would be frustrating to type out directly.

```{r hp2}
hp(dup("16 8", 8))
```

## Transpose

In the last section there was an example showing a sequence of notes followed by the same sequence transposed one octave up. At the time, it was written out twice. Here, the same sequence is reproduced using `transpose`. Transposing up one octave is done by specifying an increase of 12 semitones or half steps.
Note that `transpose` drops the unnecessary `3`s for the third octave, the central octave in LilyPond. They are dropped from `note2` here 

```{r tp1}
notes1 <- "c3 b2 c3 d3 e3 e3 d3 c3 b2 c3 c3 c4"
notes2 <- "c4 b c4 d4 e4 e4 d4 c4 b c4 c4 c5"
transpose(notes1, 12) == notes2
```

Transposing down is done with negative integers. The default (`n = 0`) returns the input, `x`, with no transposition. The alias `tp` can be used to limit typing. Examples are shown below.

```{r tp2}
transpose("a_3 b_4 c5", 0)
tp("a_3 b_4 c5", -1)
tp("a_3 b_4 c5", 1)
tp("a#3 b4 c#5", 11)
tp("a#3 b4 c#5", 12)
tp("a#3 b4 c#5", 13)
```

If no other information is passed to `transpose`, positive `n` will sharpen naturals. Negative `n` will flatten naturals. This is not ideal because it may not fit a key signature. A standard key signature is composed of notes that may include flats or sharps but not both. To avoid simply defaulting to one or the other based on direction of transposition, specify they key signature with `key` to be formal, e.g. `key = "dm"`, or just specify `"flat"` or `"sharp"`" because this is really all that is needed.

Since `notes` can be arbitrarily short, even a single note, there is no reason for `transpose` to attempt to guess the original or new key from the notes present and degree of transposition. `notes` may easily include accidentals anyhow. `transpose` works with either integer or tick style octave numbering as shown below and the the output `style` can be forced either way.

```{r tp3}
tp("a3 b4 c5", 2, key = "f")
tp("a3 b4 c5", 2, key = "g", style = "tick")
tp("a b' c''", 2, key = "flat")
tp("a, b c'", 2, key = "sharp", style = "integer")
```

The key of F has one flat (B flat) and the key of G has one sharp (F sharp). Transposing the above notes up by a whole step (two semitones or half steps) results in a new note sequence that includes either a D flat or C sharp for the second note. This pitch does not occur (except as an accidental) in either of those keys. 

Nevertheless, because F is a key with some number of sharps and G is a key with some number of flats, transpositions resulting in any non-natural notes are represented as flats and sharps, respectively. The key of C major and its relative A minor have only natural notes. Setting `key "c"` or `key = "am"` results in the default behavior, falling back on sharp notes for transposing up and flat notes for transposing down.

## Tuplets

An important feature is the tuplet. This will evenly fit a sequence of notes into a number of beats not otherwise permitted by the time signature. The most common and default tuplet returned by `tuplet` is the triplet. There is also an alias function, `triplet` for this. The triplet fits three equally spaced notes into two beats that would normally be taken up by two of those notes, meaning each note in the triplet lasts for two thirds the normal duration. The examples below show the equivalence of default `tuplet` settings and `triplet` as well as other specifications for `tuplet` and the ability to specify multiple consecutive tuplets of a fixed pattern with a single call to `tuplet`.


```{r tuplet1}
x <- "c4 d4 e4"
tuplet(x, 8)
triplet(x, 8) # equivalent
tuplet(dup(x, 2), 8, a = 6, b = 4) # 6 notes per 4 beats
tuplet(dup(x, 4), 8) # multiple tuplets, one call
```

Like `phrase`, these functions accept a `string` number argument, which is critical as usual (try engraving the final phrase below without explicit string numbers and see the mess you get). This example includes some rests.

```{r tuplet2, results="hide", eval=FALSE}
p1 <- glue(triplet("c4 r e4", 8, "4 3 3"), 
           tuplet("f4 g4 a4 b4 c5 b4", 8, "3 2 2 1 1 1", 6, 4), 
           tuplet("a4 r f4 g4 r e4 f4 e4 d4 e4 d4 c4", 16, "2 2 3 2 3*7 4"),
           tuplet("b a g f e", 16, "4 4 5*3", 5, 4))
track(glue(p1, p("d c", "8 4.", "6 6"))) %>% score %>% tab("ex12.pdf")
```

<p align="center"><img src="https://github.com/leonawicz/tabr/blob/master/data-raw/vignette-pngs/ex12.png?raw=true" width="100%"></p>

This concludes the section on helper functions associated with phrases and note sequences. The next section goes into deeper detail on chord specification and the various use of chords in `tabr`.

```{r cleanup, echo=FALSE}
unlink("*.mid")
```
