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

[Duncan Murdoch]

On 25/01/2024 12:38 p.m., Henrik Bengtsson wrote:
> On Thu, Jan 25, 2024 at 8:27 AM Duncan Murdoch <murdoch.duncan using 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.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?
> 
> 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