Naming and API consistency (meta issue)

[lionel-]

rlang is still a bit unstable because one of its major goal is the consistency of its API. We think a lot about naming before introducing features but it takes some actual experience with the library to figure it out. We're aiming for reaching stability after 1 or 2 more releases. Thus rlang 0.2.0 will involve several changes, some of them backward incompatible.

This does not apply to the tidy evaluation tools exported in other tidyverse packages. These will remain completely stable. See this template for a list: https://github.com/r-lib/usethis/blob/master/inst/templates/tidy-eval.R

We are working on https://github.com/lionel-/oldie to ease up the transition, deprecated functions will still work silently for one release but it will be possible to make them noisy so that package authors can detect changes early. In particular the next version of testthat promotes all deprecation levels so packages using testthat will be alerted of changes quickly.

Fixable with deprecation cycle

• More consistent use of abbreviations:

  Complements should not be abbreviated:

  is_environment <- is_env
  get_environment <- get_env
  get_expression <- get_expr
  is_language <- is_lang

  Return values should be abbreviated:

  parse_quo <- parse_quosure

  Piecewise constructors should not be abbreviated and should start with new_ prefix:

  new_environment <- new_env
  new_logical <- lgl_len
  new_logical_along <- lgl_along

• Use poke instead of set for stateful operations:

  node_poke_car <- mut_node_car
  env_poke <- env_set  # Though `env_set()` was not published to CRAN yet

• set_attrs() should act like attributes<- and overwrite the whole set of attributes (this is for consistency with the new add_ vs set_ rules, the former should be used in order to preserve existing elements). But it also should not use an abbreviation so the new behaviour can go in set_attributes() and this does not break compatibility.

Backward incompatible

• Order of new_function() arguments should be body, args = list(), env = caller_env() instead of taking non-optional arguments first. This makes it more natural to create functions of no arguments programatically (e.g. flowery iterators):

  expr <- quote(cat("blip\n"))
  new_function(expr)

  On the other hand maybe it should be new_closure()? We'd talk about fn and function only when primitive functions are relevant. In this case we can make it work without breaking compatibility.

• Order of rep_along() arguments should be reversed so it's consistent with seq_along() and so it's pipe-friendly.

[egnha]

This does not apply to the tidy evaluation tools exported in other tidyverse packages. These will remain completely stable.

Could you list here what those functions/tools would be? That would be quite helpful for package writers depending on rlang (but not universally conversant in the tidyverse per se, e.g., myself).

In any case, thanks for opening this issue.

[lionel-]

Good idea, here they are: https://github.com/r-lib/usethis/blob/master/inst/templates/tidy-eval.R

[lionel-]

There is now a documentation topic that indicates the life cycle stage of exported functions: ?rlang::lifecycle. The stable rlang functions are all mentioned there.