Recognising tokens

The secret sauce of the package is that it recognises the ‘tokens’ that make up an R expression. So the assignment operator, <-, is recognised as a single token rather than the less-than (<) and hyphen (-) characters typed sequentially.

This power is brought to {r2eng} thanks to {lintr}, a package by Jim Hester that assesses your code for possible errors and style improvements.

An important part of this process is parsing R expressions and recognising tokens using the lintr::get_source_expressions() function. For example, that <- operator is recognised as the special token LEFT_ASSIGN under the hood.

This is some deep R magic. You can see a special grammar file file in the R source code that carries these mappings.²

Put simply, {r2eng} hijacks this process, adds a step that maps each token to English terms, then recombines the text into a sentence.

Speech

By default, {r2eng} will translate an R expression and then your computer will speak it out loud.

This is relatively straightforward on a Mac: the resulting English text is handed to your machine with a system() call and is vocalised by the built-in VoiceOver text-to-speech converter. This functionality is not built into Windows by default, so the system() call fails silently.

Of course, this assumes that VoiceOver will do a good job of parsing the English expression from {r2eng}, but that isn’t guaranteed because of issues like localised pronunciation and uncommon words. I’ve written before about how text-to-speech isn’t necessarily that good at recognising R package names, for example.

In theory, and assuming that the translation gets good, {r2eng} could be used as a simple accessibility tool because it can interpret R-specific tokens in a way that VoiceOver cannot.

The translate() function

There are two main functions in {r2eng}: translate() and translate_string(). They convert from a bare or quoted R expression, respectively, to English.

translate() takes advantage of non-standard evaluation: you pass bare (i.e. unquoted) R code to the expression argument and a few things happen.

translate(data <- 1 + 1)

## Original expression: data <- 1 + 1
## English expression: data gets 1 plus 1

First, it prints both the original R expression and the corresponding English translation. Second, and only if you are using macOS, the English string is passed to a system command that vocalises the string.

Here’s a more complex example using some {dplyr} functions. Note that we don’t need to attach {dplyr} to be able to translate.

translate(
  data %>% select(x, y) %>% dplyr::filter(y == "example"),
  function_call_end = ""
)

## Original expression: data %>% select(x, y) %>% dplyr::filter(y == "example")
## English expression: data then select open paren x , y close paren then dplyr double-colon filter open paren y double equals string "example" close paren

Note the function_call_end argument in this example. The default is "of ", which would would have made the translation data then select of open paren x y close paren, etc. Feedback suggested that this was how some users spoke the English translation out loud, so the functionality has been included for now.

While translate() takes a bare expression, translate_string() takes a string.

library(magrittr)  # attach for pipes

## Warning: package 'magrittr' was built under R version 3.6.2

"data<-1+1" %>%
  translate_string(speak = FALSE)

## Original expression: data <- 1 + 1
## English expression: data gets 1 plus 1

We get the same sort of output as the translate() example, but this time I set the speak argument to FALSE to stop the English text from being ‘spoken’ by my computer and I also eliminated spaces from the input to demonstrate that they’re ignored.

r2eng objects

Of course, you can assign a translation to an object.

my_translation <- 
  translate(data <- 1 + 1, speak = FALSE)

The object is a special r2eng S3 class of object, which is also a list.

class(my_translation)

## [1] "list"  "r2eng"

You can apply some methods to such an object: print(), speak() and evaluate().

Print the object to see that custom console output again:

print(my_translation)

## Original expression: data <- 1 + 1
## English expression: data gets 1 plus 1

Re-call the system command that ‘speaks’ the R expression out loud (again, only on macOS).

speak(my_translation)

And you can actually evaluate the R expression you supplied to translate() in the first place. So the expression we supplied, data <- 1 + 1, is evaluated so that calling data gives us the result of 1 + 1.

evaluate(my_translation)
data

## [1] 2

r2eng-class list elements

You can also access the R expression, the English translation and the mapping between them as elements of your r2eng list object.

Here’s the R expression again:

my_translation$r_expression

## [1] "data <- 1 + 1"

And the translated output:

my_translation$eng_expression

## [1] " data gets 1 plus 1 "

And a data.frame object that contains the mapping.

map <- my_translation$translation_map
map[map$text != "", ]  # filter out text spaces

##         token text  eng
## 1      SYMBOL data data
## 2 LEFT_ASSIGN   <- gets
## 4   NUM_CONST    1    1
## 6         '+'    + plus
## 7   NUM_CONST    1    1

This element is a good summary of what {r2eng} is doing under the hood: it breaks the R expression into recognised tokens and maps words to them where it knows what the corresponding English for that token should be. So <- is recognised as the token LEFT_ASSIGN, which is mapped internally to the English text gets.

RStudio Addin

The print() and speak() functions can be accessed via an RStudio addin that’s installed with the package (you may need to restart RStudio after installation). To use them, highlight an R expression in your script and select from the RStudio addins menu:

• ‘Speak R Expression In English’ to vocalise the expression through your computer’s speakers (macOS only)
• ‘Print R Expression In English’ to output an English translation to the console

These can be mapped to keyboard shortcuts so you can highlight and translate quickly without specifically calling translate() and print() or speak().

Binder demo

Maybe you don’t want to install the package. That’s fine. Instead, you can try out the package by opening this Binder instance of RStudio with {r2eng} and the tidyverse pre-installed. Click this badge to launch it:

The downside is that you can’t use the speak method. Make sure to set the argument speak = FALSE in translate() or translate_string(), or you’ll get a warning message when you run your code.

You can find the source for this at the try-r2eng GitHub repo and you can read one of my posts on how to set up Binder using Karthik Ram’s {holepunch} package.