[Rd] Repeated library() of one package with different include.only= entries

[Duncan Murdoch]

On 11/04/2024 7:04 a.m., Martin Maechler wrote:
>>>>>> Michael Chirico
>>>>>>      on Mon, 8 Apr 2024 10:19:29 -0700 writes:
> 
>      > Right now, attaching the same package with different include.only= has no
>      > effect:
> 
>      > library(Matrix, include.only="fac2sparse")
>      > library(Matrix)
>      > ls("package:Matrix")
>      > # [1] "fac2sparse"
> 
>      > ?library does not cover this case -- what is covered is the _loading_
>      > behavior of repeated calls:
> 
>      >> [library and require] check and update the list of currently attached
>      > packages and do not reload a namespace which is already loaded
> 
>      > But here we're looking at the _attach_ behavior of repeated calls.
> 
>      > I am particularly interested in allowing the exports of a package to be
>      > built up gradually:
> 
>      > library(Matrix, include.only="fac2sparse")
>      > library(Matrix, include.only="isDiagonal") # want: ls("package:Matrix") -->
>      > c("fac2sparse", "isDiagonal")
>      > ...
> 
>      > It seems quite hard to accomplish this at the moment. Is the behavior to
>      > ignore new inclusions intentional? Could there be an argument to get
>      > different behavior?
> 
> As you did not get an answer yet, ..., some remarks by an
> R-corer who has tweaked library() behavior in the past :
> 
> - The `include.only = *` argument to library() has been a
>    *relatively* recent addition {given the 25+ years of R history}:
> 
>    It was part of the extensive new features by Luke Tierney for
>    R 3.6.0  [r76248 | luke | 2019-03-18 17:29:35 +0100], with NEWS entry
> 
>      • library() and require() now allow more control over handling
>        search path conflicts when packages are attached. The policy is
>        controlled by the new conflicts.policy option.
> 
> - I haven't seen these (then) new features been used much, unfortunately,
>    also not from R-core members, but I'd be happy to be told a different story.
>    
> 
> For the above reasons, it could well be that the current
> implementation {of these features} has not been exercised a lot
> yet, and limitations as you found them haven't been noticed yet,
> or at least not noticed on the public R mailing lists, nor
> otherwise by R-core (?).
> 
> Your implicitly proposed new feature (or even *changed*
> default behavior) seems to make sense to me -- but as alluded
> to, above, I haven't been a conscious user of any
> 'library(.., include.only = *)' till now.

I don't think it makes sense.  I would assume that

   library(Matrix, include.only="isDiagonal")

implies that only `isDiagonal` ends up on the search path, i.e. 
"include.only" means "include only", not "include in addition to 
whatever else has already been attached".

I think a far better approach to solve Michael's problem is simply to use

   fac2sparse <- Matrix::fac2sparse
   isDiagonal <- Matrix::isDiagonal

instead of messing around with the user's search list, which may have 
been intentionally set to include only one of those.

So I'd suggest changing the docs to say

"[library and require] check and update the list of currently attached
packages and do not reload a namespace which is already loaded.  If a 
package is already attached, no change will be made."

Duncan Murdoch