Resolve pattern name conflicts — prefer

prefer_pattern() sets which pattern a bare pattern name resolves to, taking priority over all other patterns with that name. unprefer_pattern() removes such preferences. conflicting_patterns() returns the available patterns whose bare name is shared by more than one pattern (see register_pattern() for how bare names are resolved). Using such a bare name throws an error unless a preference has been set.

Usage

prefer_pattern(pattern)

unprefer_pattern(pattern)

conflicting_patterns()

Arguments

pattern: A character vector. For prefer_pattern() the qualified names "owner::name" of the preferred patterns where owner is either the package that registered it ("gridpattern" for the builtin patterns) or "R_GlobalEnv" for patterns registered by the user e.g. c("gridpattern::stripe", "R_GlobalEnv::wave"). Can't contain more than one pattern with the same bare name. If length zero (e.g. character(0) or NULL) then prefer_pattern() does nothing. For unprefer_pattern() bare pattern names e.g. "stripe" (removes any preference for that name) and/or qualified names (only removes the preference if it is for that pattern).

Value

prefer_pattern() and unprefer_pattern() invisibly return a character vector of the qualified names of the previous preferences (for the bare names in pattern) that existed (character(0) if there weren't any). conflicting_patterns() returns (for just the conflicting patterns) a data frame with columns

name: The pattern name.
owner: The package that registered the pattern or "R_GlobalEnv" for the user.
kind: Either "geometry" or "array".
source: One of "builtin", "register_pattern", or "options".
active: Whether the bare name currently resolves to this pattern.

Details

prefer_pattern() and unprefer_pattern() are vectorized and return the previous preferences (if any) so they may be used to temporarily change preferences:

old <- prefer_pattern(new)
# ... use patterns ...
unprefer_pattern(new)
prefer_pattern(old) # does nothing if `old` is empty

Preferences only last for the current R session. Users may put prefer_pattern() calls in their .Rprofile (or scripts) to make them persistent. Packages should not call prefer_pattern() and should instead refer to patterns by their qualified name "pkg::name".

Examples

create_pattern_polygon <- function(params, boundary_df, aspect_ratio, legend = FALSE) {
  grid::polygonGrob(boundary_df$x, boundary_df$y, boundary_df$id,
                    gp = grid::gpar(fill = params$pattern_fill))
}
x_hex <- 0.5 + 0.5 * cos(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
y_hex <- 0.5 + 0.5 * sin(seq(2 * pi / 4, by = 2 * pi / 6, length.out = 6))
# don't clobber any pre-existing user "stripe" pattern
run_example <- !has_pattern("R_GlobalEnv::stripe")
if (run_example) {
  # temporarily remove any pre-existing "stripe" preference
  old <- unprefer_pattern("stripe")
  register_pattern("stripe", create_pattern_polygon)
}
#> Pattern "stripe" conflicts with "gridpattern::stripe".
#> ℹ Use `prefer_pattern("R_GlobalEnv::stripe")` to use your pattern by default.

if (run_example) {
  print(conflicting_patterns())
}
#>     name       owner     kind           source active
#> 1 stripe gridpattern geometry          builtin  FALSE
#> 2 stripe R_GlobalEnv geometry register_pattern  FALSE

if (run_example) {
  # bare "stripe" is now ambiguous
  grid::grid.newpage()
  try(grid.pattern("stripe", x_hex, y_hex))
}
#> Error : Pattern "stripe" registered by 2 owners.
#>   Either pick the one you want with `::`:
#> • "R_GlobalEnv::stripe"
#> • "gridpattern::stripe"
#>   Or declare a preference with `prefer_pattern()`:
#> • `prefer_pattern("R_GlobalEnv::stripe")`
#> • `prefer_pattern("gridpattern::stripe")`

if (run_example) {
  # prefer the user's "stripe" pattern over the builtin "stripe" pattern
  prefer_pattern("R_GlobalEnv::stripe")
  grid::grid.newpage()
  grid.pattern("stripe", x_hex, y_hex, fill = "blue")
}


if (run_example) {
  print(conflicting_patterns())
}
#>     name       owner     kind           source active
#> 1 stripe gridpattern geometry          builtin  FALSE
#> 2 stripe R_GlobalEnv geometry register_pattern   TRUE

if (run_example) {
  # remove the preference
  unprefer_pattern("stripe")
  # remove "R_GlobalEnv::stripe" (not "gridpattern::stripe")
  unregister_pattern("stripe")
  # restore any pre-existing preference
  prefer_pattern(old)
}