[Rd] Fwd: Document colon equals `:=` operator ?

[Ant F]

Dear all,

There was some discussion lately on twitter (
https://twitter.com/geospacedman/status/1164208293377691648 ) about the
status of the colon equal operator. I'm sure it has been discussed in the
past but I couldn't find anything, I'll start by clarifying all i can by
myself to have strong reference, and then ask a few questions at the bottom.

`:=` has been used by data table for a very long time and more recently by
tidyverse packages through rlang package, in both cases to parse
expressions (it's also defined and exported by data.table but just to
trigger an error). It was used in ggvis too, and I have myself designed the
package dotdot that defines it. I'm note aware of other uses in packages
though it pops up from time to time in Stack Overflow 's Q&A.

It has the same precedence as `<-`.

It is used by data.table and tidyverse to provide key / value pairs to
function arguments where `=` would trigger a failure.

It can also convenient at the top level because the rhs is NOT
evaluated/copied before entering the function, as it is with `=` and `<-`.

My understanding based on :

* John Chambers 2001 : https://developer.r-project.org/equalAssign.html
* Matt Dowle 2011 :
https://stackoverflow.com/questions/7033106/why-has-data-table-defined-rather-than-overloading

is that `:=` used to be an equivalent to `<-`, along with `_`. At some
point the decision was made to remove `_` and `:=`. BUT, and as I
understand it started as a mistake,  the `:=` operator was kept (without
definition).

Then Matt Dowle used it in data.table, which gained tremendous popularity,
and thus it was kept around, and later implemented by Hadley Wickham and
Lionel Henry in rlang as a central component of tidy evaluation.

?data.table::`:=` and ?rlang::`:=` describe how to use the operator in the
context of the package but don't refer to its undocumented status.

Some relevant chunks of source code :

*
https://github.com/wch/r-source/blob/tags/R-3-6-1/src/main/gram.y#L379-L381
*
https://github.com/wch/r-source/blob/tags/R-3-6-1/src/main/gram.y#L2999-L3002

Now for the questions :

Some R users worry that the use of `:=` is not safe, as it is
undocumented.  It would be good to be able for package authors to reassure
their users that the package won't break because R Core decides to remove
the operator at some point, or change its behavior.

* Could we have an official statement that the `:=` operator is NOT going
to be removed and can be used safely in packages ? OR could we have an
official statement that the use of the `:=` is discouraged and unsafe given
it might be removed at some point

* If we can have confirmation that the operator won't be removed (and thus
can be used for parsing), could we also have an official statement that it
will also remain possible to define it ? (which data.table and tidyverse
don't require for instance, but dotdot does) OR have a statement that
assuming this is not safe.

* Could we have these statements reflected in the doc ? Or why can't we ? I
believe that even if R Core discourages the use of `:=`, this should be
reflected in the doc. Users encountering it should still be able to
understand what's going on through the base documentation. Referencing it
in `?Syntax` along with a short note would go a long way.

Many thanks and apologies for the possible redundancy with previous threads,

Antoine

	[[alternative HTML version deleted]]