prefer_pattern: Resolve pattern name conflicts

In gridpattern: 'grid' Pattern Grobs

Resolve pattern name conflicts

Description

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).

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".

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.

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)
}

if (run_example) {
  print(conflicting_patterns())
}

if (run_example) {
  # bare "stripe" is now ambiguous
  grid::grid.newpage()
  try(grid.pattern("stripe", x_hex, y_hex))
}

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())
}

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)
}

gridpattern documentation built on Oct. 28, 2026, 5:06 p.m.