Skip to contents

Generate a re-usable highlight function

Source: R/highlight.R
highlighter.Rd

Generates a partially applied version of the highlight() function, with pre-supplied tests .t and formatters .f.

The following calls produce equivalent highlighted vectors:

  • highlight(.x = .x, .t = .t, .f = .f)

  • highlighter(.t = .t, .f = .f)(.x = .x)

This is useful for creating and storing a re-usable conditional format to apply to vectors.

highlighter_mult() and highlighter_case() (corresponding to highlight_mult() and hightlight_case()) allow .t and .f to be supplied as two-sided formulas .t ~ .f using dplyr::case_when() style syntax.

Usage

highlighter(.t, .f)

highlighter_mult(...)

highlighter_case(...)

Arguments

.t

[function / list]

Vectorized test functions specified as:

  • A named function, e.g. is.na

  • An anonymous function, e.g. \(x) 0 <= x & x <= 1

  • A purrr-style lambda, e.g. ~ nchar(.x) > 0, ~ .h == 1, ~ TRUE

  • A list of functions or lambdas, e.g. list(~ .x < mean(.x), is.finite)

In the generated function, each function in .t will receive a vector .x as it's input and must return a logical vector the same length as .x or of length 1 (in which case the result will be recycled to the length of .x).

.f

[function / list]

Vectorized character manipulation functions specified as:

  • A named function, e.g. cli::style_bold

  • An anonymous function, e.g. \(words) gsub("hi", "hey", words)

  • A purrr-style lambda, e.g. ~ paste0(.h, "!"), ~ "fizz"

  • A list of functions or lambdas, e.g. list(~ cli::col_red(.x), toupper)

In the generated function, each formatter function in .f will receive a character vector (of variable length) as it's only argument. A formatter must return a character vector the same length as it's input or of length 1 (in which case the result is recycled to the length of the input character).

...

[formula / vlightr_highlighter]

For highlighter_mult() and highlighter_case(), a two sided formula with a test on the left-hand-side and a formatter on the right-hand-side. This argument replaces the .t and .f arguments of highlighter(). The ith dot ..i is roughly equivalent to .t[[i]] ~ .f[[i]].

See the ... argument of highlight() for more details on valid arguments to supply to ....

Value

A function of class vlightr_highlighter. For highlighter_case(), a function of class vlightr_highlighter/vlightr_highlighter_case.

Examples

# Mimic an existing highlighted vector
indicator <- c(1, 0, 1, 0)
indicator_hl <- highlight_mult(
 indicator,
 0 ~ label("No"),
 1 ~ label("Yes")
)
indicator_hltr <- highlighter_mult(
 0 ~ label("No"),
 1 ~ label("Yes")
)

# These print the same result
print(indicator_hl)
#> <highlight<double>[4]>
#> [1] 1 [Yes] 0 [No]  1 [Yes] 0 [No] 
print(indicator_hltr(indicator))
#> <highlight<double>[4]>
#> [1] 1 [Yes] 0 [No]  1 [Yes] 0 [No] 

# You can add functionality to an existing highlighter by
# providing it as an argument to `highlighter_mult()`.
new_indicator_hltr <- highlighter_mult(
  indicator_hltr,
  5 ~ "Maybe",
  is.na ~ "?"
)
x <- c(0, 1, NA, 5)
indicator_hltr(x) # NA and 5 are un-formatted
#> <highlight<double>[4]>
#> [1] 0 [No]  1 [Yes] NA      5      
new_indicator_hltr(x) # NA and 5 are formatted
#> <highlight<double>[4]>
#> [1] 0 [No]  1 [Yes] ?       Maybe  

# This is useful for composing highlighters
exclaim <- highlighter(~ .x == toupper(.x), ~ paste0(.x, "!"))
question <- highlighter(~ .x == tolower(.x), ~ paste0(.x, "?"))
punctuate <- highlighter_mult(exclaim, question)

# `punctuate()` applies the formatting of `exclaim()` and `question()`
phrases <- c("hi all", "FANTASTIC", "I'm Dave")
exclaim(phrases)
#> <highlight<character>[3]>
#> [1] "hi all"     "FANTASTIC!" "I'm Dave"  
question(phrases)
#> <highlight<character>[3]>
#> [1] "hi all?"   "FANTASTIC" "I'm Dave" 
question(punctuate)
#> Error in question(punctuate): `.x` must be a non-bare-list and non-dataframe vector, not a
#> <vlightr_highlighter> object.
#> ℹ See `?vctrs::obj_is_vector()` for details on vectors.

# `highlighter_case()` uses the same matching behavior as
# `highlight_case()`.
fullstop <- highlighter(~ TRUE, ~ paste0(.x, "."))
punctuate_mult <- highlighter_mult(punctuate, fullstop)
punctuate_case <- highlighter_case(punctuate, fullstop)

# A period is added to every phrase, since the `fullstop()`
# test always returns `TRUE`
punctuate_mult(phrases)
#> <highlight<character>[3]>
#> [1] "hi all?."    "FANTASTIC!." "I'm Dave."  

# A period is only added to elements of phrase not already
# matched by a previous test.
punctuate_case(phrases)
#> <highlight_case<character>[3]>
#> [1] "hi all?"    "FANTASTIC!" "I'm Dave."