arrow

ARROW-15010: [R] Create a function registry for our NSE funcs

This is PR implementing that admittedly does a few things. I'd be happy to split up with a suggestion on the desired steps if that makes it easier to review. In fact, I'm totally game to use reviews on this PR to collect ideas about the changes that collectively we agree on and just implement that subset in a new PR.

This PR:

- Defines `register_translation()` and `register_translation_agg()` instead of direct assignment into `nse_funcs` and `agg_funcs`. This enables attaching a package name when the function is being registered (e.g., `register_translation("stringr::str_dup", function(x, ...) ...)`) and makes it possible in the future to allow other packages to define translations and/or for us to change how we evaluate translated expressions without changing many function assignments.
- Moves the registration of translations to package load time rather than package build time. This enables splitting up translations into multiple files, adds the usual CMD check that normal functions undergo (e.g., for use of missing variables), and opens up the possibility of defining different translations for different versions of packages (or omitting translations if a package isn't installed).
- Splits up the definition of translations into dplyr-funcs-type.R, dplyr-funcs-conditional.R, dplyr-funcs-string.R, dplyr-funcs-datetime.R, and dplyr-funcs-math.R. This matches where the translations are tested (the test files were named test-dplyr-funcs-string.R, etc.). Some translations were moved to dplyr-summarise.R because the translations were being tested in test-dplyr-summarise.R. This makes it easier for parallel PRs defining translations and makes it easier for new contributors to figure out where tests should go.
- Consolidates internal documentation on how to write translations into one .Rd file rather than scattered around as comments in dplyr-functions.R as they were before.
- Removes direct references to `nse_funcs` and `agg_funcs` except where used to implement evaluation

This PR does not:

- Change any test filenames or remove any tests.
- Change how translations are stored in the package namespace
- Change anything about how evaluation works

Reprex with the gist of how the registration works:

``` r
# remotes::install_github("apache/arrow/r#11904")
withr::with_namespace("arrow", {

  # translations get defined in function wrappers so that they can get called
  # at package load (so there's no need to consider collate order)
  register_file_translations <- function() {

    register_translation("some_func", function() {
      Expression$scalar(1L)
    })

  }

  # the .onLoad() hook for registering translations lives in dplyr-funcs.R
  register_all_translations <- function() {
    register_file_translations()
    # ...and other translation functions that might live in other files
  }

  # ...and gets called in .onLoad()
  register_all_translations()

  # if you need to call a translation, use call_translation() (to keep references
  # to nse_funcs and/or agg_funcs constrained to the eval implementation)
  call_translation("some_func")

  # ...the same machinery exists for agg_funcs
  register_translation_agg("some_agg_func", function() {
    Expression$scalar(2L)
  })

  call_translation_agg("some_agg_func")
})
#> Expression
#> 2
```

<sup>Created on 2021-12-08 by the [reprex package](https://reprex.tidyverse.org) (v2.0.1)</sup>

Closes #11904 from paleolimbot/r-register-translation

Lead-authored-by: Dewey Dunnington <dewey@fishandwhistle.net>
Co-authored-by: Jonathan Keane <jkeane@gmail.com>
Signed-off-by: Jonathan Keane <jkeane@gmail.com>