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. Like registered_patterns() it never loads any packages.

Usage

prefer_pattern(pattern, must_exist = NA)

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).
must_exist: What to do if a preferred pattern isn't (yet) registered. If TRUE throw an error, if NA throw a warning, and if FALSE do nothing. In all cases the preference is set (unless there is an error) and takes effect once the pattern is registered e.g. once its package is loaded. If FALSE the existence of the patterns isn't checked at all (in particular their packages aren't loaded), which is useful in an .Rprofile or to prefer a user pattern before it is registered. Otherwise the packages of the preferred patterns are loaded (if installed). must_exist likewise controls what happens if the user has more than one pattern with that name (only possible via the legacy ggpattern_geometry_funcs / ggpattern_array_funcs options, see register_pattern()) since a preference can't choose between them (an error is thrown once the pattern is used).

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 (without loading the package of a preferred pattern, see prefer_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

local_prefer_pattern() does this automatically when the current function (or test) exits.

Preferences only last for the current R session. Users may put prefer_pattern() calls in their .Rprofile (or scripts) to make them persistent (use must_exist = FALSE in an .Rprofile to avoid loading the packages at startup). A bare name with a preference for a pattern that isn't registered is an error (but if its package isn't loaded it is loaded first). Packages should not call prefer_pattern() and should instead refer to patterns by their qualified name "pkg::name" (although packages may use local_prefer_pattern() in their tests and examples so bare names resolve to their patterns there).

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 "fill" pattern
run_example <- !has_registered_pattern("R_GlobalEnv::fill")
if (run_example) {
  # temporarily remove any pre-existing "fill" preference
  old <- unprefer_pattern("fill")
  register_pattern("fill", create_pattern_polygon)
}
#> Pattern "fill" conflicts with "gridpattern::fill".
#> ℹ Use `prefer_pattern("R_GlobalEnv::fill")` to use your pattern by default.

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

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

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


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

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