[R-pkg-devel] Native pipe in package examples

[Duncan Murdoch]

On 25/01/2024 11:18 a.m., Henrik Bengtsson wrote:
> On Thu, Jan 25, 2024 at 7:48 AM Duncan Murdoch <murdoch.duncan using 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?

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 would say that a package that doesn't pass "R CMD check" without 
errors shouldn't be trusted.

Duncan Murdoch