On 25/01/2024 12:38 p.m., Henrik Bengtsson wrote:
On Thu, Jan 25, 2024 at 8:27 AM Duncan Murdoch <murdoch.dun...@gmail.com> wrote:
On 25/01/2024 11:18 a.m., Henrik Bengtsson wrote:
On Thu, Jan 25, 2024 at 7:48 AM Duncan Murdoch <murdoch.dun...@gmail.com> wrote:
On 25/01/2024 10:27 a.m., Josiah Parry wrote:
Hey all,
I've encountered use of the native pipe operator in the examples for
'httr2' e.g.
request("http://example.com";) |> req_dry_run()
Since r-oldrel (according to rversions::r_oldrel()) is now 4.2.3, can the
native pipe be used in example code?
I do notice that the package httr2 requires R >= 3.6.0 which implies that
the code itself does not use the native pipe, but the examples do.
I think that the package should state it requires R (>= 4.1.0), since
that code won't work in earlier versions.
I believe it's a syntax error before 4.1.0, but don't have a copy handy
to test.
Yes, support for the |> syntax was introduced in R 4.1.0;
$ Rscript --vanilla -e "getRversion()" -e "1:10 |> sum()"
[1] ‘4.0.5’
Error: unexpected '>' in "1:10 |>"
Execution halted
$ Rscript --vanilla -e "getRversion()" -e "1:10 |> sum()"
[1] ‘4.1.0’
[1] 55
That means the package won't pass R CMD check in those old
versions. If it wasn't a syntax error, just a case of using a new
feature, then I think it would be fine to put in a run-time test of the
R version to skip code that won't run properly.
There's also the distinction of package code versus code in
documentation. If it's only example code in help pages that use the
native pipe, but the code in R/*.R does not, then the package will
still install and work with R (< 4.1.0). The only thing that won't
work is when the user tries to run the code in the documented
examples. I'd argue that it's okay to specify, say, R (>= 3.6.0) in
such an example. It allows users with older versions to still use the
package, while already now migrating the documentation to use newer
syntax.
Is there a way to do that so that R will pay attention, or do you mean
just saying it in a comment?
As a "comment".
I think you're right that syntax errors in help page examples will be
installable, but I don't think there's a way to make them pass "R CMD
check" other than wrapping them in \dontrun{}, and I don't know a way to
do that conditional on the R version.
I think
$ R CMD check --no-examples --no-vignettes ...
would check everything else but examples and vignettes.
I would say that a package that doesn't pass "R CMD check" without
errors shouldn't be trusted.
Somewhat agree, but we still get some "trust" from the fact that the
package passes R CMD check --as-cran on R (>= 4.1.0). Also, if the
maintainer documents something like "On R (> 4.1.0), the package
passes 'R CMD check --no-examples ...'; we use R (>= 4.1.0)-specific
syntax in some of the help-age examples", then there's additional
"trust" in it's working there. But, yes, there's less "trust" here,
but I think it's okay for maintainers to declare "R (>= 3.6.0)" to be
backward compatible. Another way to put it, it would be extreme to
require "R (>= 4.1.0)" just because of a single "1:3 |> sum()" in some
example code.
/Henrik
PS. Personally, I'd skip the use of |> in examples to avoid these concerns.
I think we agree. If I was determined to support 3.6.0 users, I'd
recode that example as
req_dry_run(request("http://example.com";))
# It is convenient to use the native pipe |> in R 4.1.0 or greater:
# request("http://example.com";) |> req_dry_run()
# ... or the magrittr pipe if available:
# request("http://example.com";) %>% req_dry_run()
Duncan Murdoch
______________________________________________
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
