These helper functions add some validation checks for phrase and candidate phrase objects.

as_phrase(phrase)

phrasey(phrase)

notify(phrase)

phrase_notes(phrase, collapse = TRUE)

phrase_info(phrase, collapse = TRUE, annotations = TRUE)

phrase_strings(phrase, collapse = FALSE)

notable(phrase)

Arguments

phrase

phrase object or character string (candidate phrase).

collapse

logical, collapse result into a single string ready for phrase construction.

annotations

logical, strip any text annotations from the note info converted from phrase().

Value

see details for each function's purpose and return value.

Details

Use these functions with some caution. They are not intended for strictness and perfection. phrasey() checks whether an object is weakly phrase-like and returns TRUE or FALSE. It can be used to safeguard against the most obvious cases of phrase() not containing valid phrase syntax when programming. However, it may also be limiting. Use wear sensible.

as_phrase() coerces an object to a phrase object if possible. This function performs an internal phrasey() check.

notify() attempts to decompose a phrase object back to its original input vectors consisting of notes, note info, and optionally, instrument string numbering. If successful, it returns a tibble data frame with columns: notes, info, string.

Unless decomposing very simple phrases, this function is likely to reveal limitations. Complex phrase objects constructed originally with phrase() can be challenging to deconstruct in a one to one manner. Information may be lost, garbled, or the function may fail. For example, this function is not advanced enough to unravel repeat notation or tuplets.

notable() returns TRUE or FALSE regarding whether a phrase can be converted back to character string inputs, not necessarily with complete correctness, but without simple failure.It checks for phrasiness. Then it tries to call notify() and returns FALSE gracefully if that call throws an exception.

Examples

# Create a list of phrase objects
p1 <- phrase("c ec'g' ec'g'", "4 4 2") # no string numbers (not recommended)
p2 <- phrase("c ec4g4 ec4g4", "4 4 2") # same as above
p3 <- phrase("c b, c", "4. 8( 8)", "5 5 5") # direction implies hammer on
p4 <- phrase("b2 c d", "4( 4)- 2", "5 5 5") # hammer and slide
p5 <- phrase("c ec'g'~ ec'g'", 1, "5 432 432") # tied chord
x <- list(p1, p2, p3, p4, p5)

# Check if phrases and strings are phrasey
sapply(x, phrasey)
#> [1] TRUE TRUE TRUE TRUE TRUE
sapply(as.character(x), phrasey, USE.NAMES = FALSE)
#> [1] TRUE TRUE TRUE TRUE TRUE

# Coerce character string representation to phrase and compare with original
y <- lapply(as.character(x), as_phrase)
identical(x, y)
#> [1] TRUE

# Check if notable
sapply(x, notable)
#> [1] TRUE TRUE TRUE TRUE TRUE
notable(p("a b c", 1))
#> [1] TRUE
notable("a b x") # note: not constructible as a phrase in the first place
#> [1] FALSE

# Notify phrases
d <- do.call(rbind, lapply(x, notify))
d
#> # A tibble: 15 × 3
#>    notes    info  string
#>    <chr>    <chr> <chr> 
#>  1 c        4     NA    
#>  2 ec'g'    4     NA    
#>  3 ec'g'    2     NA    
#>  4 c        4     NA    
#>  5 ec'g'    4     NA    
#>  6 ec'g'    2     NA    
#>  7 c        4.    5     
#>  8 b,       8(    5     
#>  9 c        8)    5     
#> 10 b,       4(    5     
#> 11 c        4)-   5     
#> 12 d        2     5     
#> 13 c        1     5     
#> 14 e~c'~g'~ 1     432   
#> 15 ec'g'    1     432   

# Wrappers around notify extract components, default to collapsed strings
phrase_notes(p5)
#> <Noteworthy string>
#>   Format: space-delimited time
#>   Values: c <e~c'~g'~> <ec'g'>
phrase_info(p5)
#> <Note info string>
#>   Format: space-delimited time
#>   Values: 1 1 1
phrase_strings(p5)
#> [1] "5"   "432" "432"

# If phrase decomposition works well, coercion is one to one
x2 <- lapply(x,
  function(x) p(phrase_notes(x), phrase_info(x), phrase_strings(x))
)
identical(x, x2)
#> [1] TRUE