Conditionally format a vector by location

templight() creates a vector with a conditional format() and print() method. The function takes an input vector .x, a vector of locations .at, and a formatter function .f. When the result of templight(.x, .at, .f) is printed, elements of .x at indices specified by .at are transformed by .f before they are printed.

.at and .f may be equal length lists of indexes and functions. Elements of .x at locations .at[[i]] are transformed using .f[[i]]. Conditional formats are applied to the highlighted vector in the order that they are applied to .at and .f.

templight_mult() and templight_case() allow these pairs of locations and functions to be supplied as two-sided formulas .at ~ .f using dplyr::case_when() style syntax.

tl() and templight() are synonyms, as are tl_mult() and templight_mult(), tl_case() and templight_case().

Usage

templight(
  .x = logical(),
  .at = logical(),
  .f = getOption("vlightr.default_formatter")
)

tl(
  .x = logical(),
  .at = logical(),
  .f = getOption("vlightr.default_formatter")
)

templight_mult(.x, ...)

tl_mult(.x, ...)

templight_case(.x, ...)

tl_case(.x, ...)

Arguments

.x

[vector]

A vector to highlight. Conceptually, a vector is a collection of objects of size 1.

.x is considered a vector if:

.x is not a data.frame
.x is not a bare list
.x is otherwise a vector, as defined by vctrs::obj_is_vector()

Atomic vector types "logical", "integer", "double", "complex", "character", and "raw" meet these criteria. As do many common vector classes such as POSIXct, lubridate::interval, or ivs::iv.

By default .x is an empty logical vector.

.at

[logical / integerish / list]

Locations of elements in .x to conditionally format, supplied as a logical, integer, or whole-numbered (e.g. 1.0, 2.00) numeric vector. .at may also be a list of such vectors.

For example, .at = c(TRUE, FALSE, TRUE) corresponds to elements 1 and 3 of .x (if they exist). As does .at = c(1, 3) and .at = c(1.0, 3.0).

By default, .at is an empty logical vector.

.f

[function / list]

Vectorized character manipulation functions used to format .x. .f may be:

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)

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

ANSI string vectors (class cli_ansi_string) are also supported (see cli::ansi-styles for details).

By default .f is the function [cli::bg_br_yellow()] which changes the background color of it's input text to bright yellow. You can modify this default by setting the vlightr.default_formatter in options().

...

[formula / vlightr_highlighter]

For templight_mult() and templight_case(), a two sided formula with locations on the left-hand-side and a formatter on the right-hand-side. This argument replaces the .at and .f arguments of templight(). The ith dot ..i is roughly equivalent to .at[[i]] ~ .f[[i]].

The left-hand-side of the formula may be:

A logical vector, e.g. c(TRUE, FALSE), letters == "r"
Numeric indices, e.g. c(1, 2, 3), which(letters %in% c("q", "r"))

The right-hand-side of the formula may be:

A named function, e.g. cli::style_hidden
An anonymous function, e.g. \(x) tolower(trimws(x))
A purrr-style lambda expression, e.g. paste(seq_along(.x), "is", .x)

A temp-lighter, e.g. templighter(c(1, 2, 3), color("blue")), may be supplied instead of a formula, in which case the arguments .at and .f of the temp-lighter are spliced into ....

In the case of templight_case(), elements of .x can be conditionally formatted at most once, similar to the behavior of dplyr::case_when().

Value

A vector of class vlightr_templight. For templight_case(), the a vector of class vlightr_templight/vlightr_highlight_case.

Details

Vectors highlighted by templight() are said to be "temporarily" conditionally formatted because the association between .at and the elements of .x is likely to exist only temporarily.

For example, the code below creates a temp-lighted vector minimum_tl which conditionally formats the minimum element of x.

x <- c(4, 3, 0, 2, 1)
minimum_tl <- templight(x, .at = x == min(x), .f = wrap("<", ">"))
print(minimum_tl) # 4 3 <0> 2 1

When the vector minimum_tl is altered, by sorting it for example, the conditionally formatted element is no longer the minimum value of x, it is whatever happens to be the third element of the temp-lighted vector.

print(sort(minimum_tl)) # 0 1 <2> 3 4

This is in contrast to vectors created using highlight(), which maintain an association between specific elements of the data x and a conditional format .f.

# Highlight the minimum element of `x` (i.e. 0)
minimum_hl <- highlight(x, .t = ~ .x == min(.x), .f = wrap("<", ">"))

# The minimum element of `x` is still highlighted after sorting
print(sort(minimum_hl)) # <0> 1 2 3 4

Examples

# TODO