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

[Duncan Murdoch]

On 25/01/2024 11:44 a.m., Josiah Parry wrote:
> The package of course passes R CMD check otherwise it wouldn’t be on 
> CRAN! (:

CRAN doesn't run checks using R 3.6.0.  The package claims it works 
there, and maybe it will, but it won't pass R CMD check.

Duncan Murdoch


> 
> Thank you Henrik! Good to know my intuition was correct. I’m glad we can 
> start to use the new features of R in package documentation :)
> 
> On Thu, Jan 25, 2024 at 11:27 Duncan Murdoch <murdoch.duncan using gmail.com 
> <mailto: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 <mailto: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 <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
>