sgr_to_html {fansi} | R Documentation |
Interprets CSI SGR sequences and produces a string with equivalent
formats applied with SPAN elements and inline CSS styles. Optionally for
colors, the SPAN elements may be assigned classes instead of inline styles,
in which case it is the user's responsibility to provide a style sheet.
Input that contains special HTML characters ("<", ">", "&", "'", and "\""),
particularly the first two, should be escaped with html_esc
.
sgr_to_html( x, warn = getOption("fansi.warn"), term.cap = getOption("fansi.term.cap"), classes = FALSE )
x |
a character vector or object that can be coerced to character. |
warn |
TRUE (default) or FALSE, whether to warn when potentially
problematic Control Sequences are encountered. These could cause the
assumptions |
term.cap |
character a vector of the capabilities of the terminal, can
be any combination of "bright" (SGR codes 90-97, 100-107), "256" (SGR codes
starting with "38;5" or "48;5"), and "truecolor" (SGR codes starting with
"38;2" or "48;2"). Changing this parameter changes how |
classes |
FALSE (default), TRUE, or character vector of either 16, 32, or 512 class names. Character strings may only contain ASCII characters corresponding to letters, numbers, the hyphen, or the underscore. It is the user's responsibility to provide values that are legal class names.
|
Only "observable" styles are translated. These include colors, background-colors, and basic styles (CSI SGR codes 1-6, 8, 9). Style 7, the "inverse" style, is implemented by explicitly switching foreground and background colors, if there are any. Styles 5-6 (blink) are rendered as "text-decoration" but likely will do nothing in the browser. Style 8 (conceal) sets the color to transparent.
Each element of the input vector is translated into a stand-alone valid HTML
string. In particular, any open SPAN tags are closed at the end of an
element and re-opened on the subsequent element with the same style. This
allows safe combination of HTML translated strings, for example by
paste
ing them together. The trade-off is that there may be redundant
HTML produced. To reduce redundancy you can first collapse the input vector
into one string, being mindful that very large strings may exceed maximum
string size when converted to HTML.
Active SPAN tags are closed and new ones open anytime the "observable"
state changes. sgr_to_html
never produces nested SPAN tags, even if at
times that might produce more compact output. This is because ANSI CSI SGR
is a state based formatting system and is not constrained by the semantics of
a nested one like HTML, so dealing with the complexity of nesting when it
cannot reproduce all inputs anyway does not seem worthwhile.
A character vector of the same length as x
with all escape
sequences removed and any basic ANSI CSI SGR escape sequences applied via
SPAN HTML tags.
Non-ASCII strings are converted to and returned in UTF-8 encoding.
fansi
for details on how Control Sequences are
interpreted, particularly if you are getting unexpected results,
set_knit_hooks
for how to use ANSI CSI styled text with knitr and HTML
output, sgr_256
to generate a demo string with all 256 8 bit colors.
Other HTML functions:
html_esc()
,
in_html()
,
make_styles()
sgr_to_html("hello\033[31;42;1mworld\033[m") sgr_to_html("hello\033[31;42;1mworld\033[m", classes=TRUE) ## Input contains HTML special chars x <- "<hello \033[42m'there' \033[34m &\033[m \"moon\"!" writeLines(x) ## Not run: in_html( c( sgr_to_html(html_esc(x)), # Good sgr_to_html(x) # Bad! ) ) ## End(Not run) ## Generate some class names for basic colors classes <- expand.grid( "myclass", c("fg", "bg"), c("black", "red", "green", "yellow", "blue", "magenta", "cyan", "white") ) classes # order is important! classes <- do.call(paste, c(classes, sep="-")) ## We only provide 16 classes, so Only basic colors are ## mapped to classes; others styled inline. sgr_to_html( "\033[94mhello\033[m \033[31;42;1mworld\033[m", classes=classes ) ## Create a whole web page with a style sheet for 256 colors and ## the colors shown in a table. class.256 <- do.call(paste, c(expand.grid(c("fg", "bg"), 0:255), sep="-")) sgr.256 <- sgr_256() # A demo of all 256 colors writeLines(sgr.256[1:8]) # SGR formatting ## Convert to HTML using classes instead of inline styles: html.256 <- sgr_to_html(sgr.256, classes=class.256) writeLines(html.256[1]) # No inline colors ## Generate different style sheets. See `?make_styles` for details. default <- make_styles(class.256) mix <- matrix(c(.6,.2,.2, .2,.6,.2, .2,.2,.6), 3) desaturated <- make_styles(class.256, mix) writeLines(default[1:4]) writeLines(desaturated[1:4]) ## Embed in HTML page and diplay; only CSS changing ## Not run: in_html(html.256) # no CSS in_html(html.256, css=default) # default CSS in_html(html.256, css=desaturated) # desaturated CSS ## End(Not run)