quickColor: Quick Colors for xterm

In cadnza/quickColor: Quick and convenient coloring for xterm-compatible terminals

Description

quickColor wraps crayon and adds the ability to reference colors by xterm number, which can be especially useful if you're trying to match a specific color from xterm's palette (though do see the caveat for system colors in Details). And it only colors text in interactive mode, so it won't mess with your scripts.

Usage

quickColor(
	txt,
	fg=NA,
	bg=NA,
	bold=FALSE
)

quickColorByScale(
	txt,
	x,
	lwr,
	upr,
	target="fg",
	fg=NA,
	bg=NA,
	clrLwr=2L,
	clrMid=11L,
	clrUpr=9L
)

quickReference()

Arguments

txt	The text to format.
fg, bg	Static foreground and background color, respectively. These should be xterm numbers (see quickReference). Setting either to NA (the default) forgoes color for that element.
bold	Whether to bold as well as color.
x	The working value on the color scale (see Details).
lwr, upr	The upper and lower bounds of the color scale (see Details).
target	Whether to apply the color scale to the foreground ("fg") (the default) or the background ("bg") (see Details). Note that if target="fg", then the fg argument must be NA. Similarly, target="bg" necessitates is.na(bg).
clrLwr, clrMid, clrUpr	The three colors of the color scale, representing the lower, middle, and upper bounds, respectively (see Details). All three should be xterm colors (see quickReference) except for clrMid, which is allowed to be NA. If clrMid is NA, the scale has no middle bound. The defaults here are green for the lower bound, yellow for middle, and red for upper.

Details

The quickColor function applies quick styling using xterm color numbers.

The quickColorByScale function applies xterm color based on a scale. Perhaps the best parallel is Excel's conditional formatting by scale, which colors values depending on where they fall on a scale. With quickColorByScale, you specify text (txt), scale boundaries (lwr and upr), a numeric value on the scale (x), whether to dynamically color the foreground or background (target), a static color for the other element (fg or bg), and boundary colors (clrLwr, clrMid, and clrUpr), and quickColorByScale returns back the text nicely colored.

The middle boundary clrMid is the color at the mean of clrLwr and clrUpr; see Examples for how it works. Omitting clrMid reverts quickColorByScale to a simple scale between clrLwr and clrUpr.

Also note that setting x to a value outside clrLwr:clrUpr sets the dynamic color returned to either clrLwr or clrUpr, depending on which value x exceeds.

With quickColor and quickColorByScale, you might notice that xterm colors 0 to 15 don't always behave as expected. These are system-defined colors, and they're treated as static colors in this package. To see their definitions, call quickReference() and note the Definition field.

NOTE: This package doesn't validate for xterm, but it's untested for terminals that don't use 256 xterm colors. The 1.0.0 release did use validation, but it turned out not to work well for styling the R prompt, so the validation's been removed.

Value

The quickColor and quickColorByScale functions return ANSI-escaped strings that must be handled with either cat or a function with similar functionality (see Examples). quickReference returns nothing.

References

256 Colors - Cheat Sheet - Xterm, HEX, RGB, HSL

Examples

# quickColor ----

final <- c()
vals <- c(NA,0:15)
fgVals <- vals
bgVals <- vals
boldVals <- c(FALSE,TRUE)
for(fgv in fgVals)
	for(bgv in bgVals)
		for (bdv in boldVals){
			result <- quickColor(
				"a",
				fg=fgv,
				bg=bgv,
				bold=bdv
			)
			final <- c(final,result)
		}
cat(final,sep="")

# quickColorByScale ----

final <- c()
mn <- 1
mx <- 20
targets <- c("fg","bg")
vals <- c(NA,0:15)
for(tar in targets)
	for(val in vals){
		if(tar=="fg"){
			fgWorking <- NA
			bgWorking <- val
		}else{
			fgWorking <- val
			bgWorking <- NA
		}
		resultRow <- c()
		for(i in mn:mx){
			result <- quickColorByScale(
				"a",
				x=i,
				lwr=mn,
				upr=mx,
				target=tar,
				fg=fgWorking,
				bg=bgWorking
			)
			resultRow <- c(resultRow,result)
		}
		resultRow <- paste(resultRow,collapse="")
		final <- c(final,resultRow)
	}
cat(final,sep="\n")

# quickReference ----

quickReference()

cadnza/quickColor documentation built on Dec. 19, 2021, 12:53 p.m.