strwrap_ctl {fansi} | R Documentation |
Wraps strings to a specified width accounting for zero display width Control
Sequences. strwrap_ctl
is intended to emulate strwrap
exactly except
with respect to the Control Sequences, while strwrap2_ctl
adds features
and changes the processing of whitespace.
strwrap_ctl(x, width = 0.9 * getOption("width"), indent = 0, exdent = 0, prefix = "", simplify = TRUE, initial = prefix, warn = getOption("fansi.warn"), term.cap = getOption("fansi.term.cap")) strwrap2_ctl(x, width = 0.9 * getOption("width"), indent = 0, exdent = 0, prefix = "", simplify = TRUE, initial = prefix, wrap.always = FALSE, pad.end = "", strip.spaces = !tabs.as.spaces, tabs.as.spaces = getOption("fansi.tabs.as.spaces"), tab.stops = getOption("fansi.tab.stops"), warn = getOption("fansi.warn"), term.cap = getOption("fansi.term.cap"))
x |
a character vector, or an object which can be converted to a
character vector by |
width |
a positive integer giving the target column for wrapping lines in the output. |
indent |
a non-negative integer giving the indentation of the first line in a paragraph. |
exdent |
a non-negative integer specifying the indentation of subsequent lines in paragraphs. |
prefix |
a character string to be used as prefix for
each line except the first, for which |
simplify |
a logical. If |
initial |
a character string to be used as prefix for
each line except the first, for which |
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 "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 |
wrap.always |
TRUE or FALSE (default), whether to hard wrap at requested
width if no word breaks are detected within a line. If set to TRUE then
|
pad.end |
character(1L), a single character to use as padding at the
end of each line until the line is |
strip.spaces |
TRUE (default) or FALSE, if TRUE, extraneous white spaces (spaces, newlines, tabs) are removed in the same way as base::strwrap does. |
tabs.as.spaces |
FALSE (default) or TRUE, whether to convert tabs to
spaces. This can only be set to TRUE if |
tab.stops |
integer(1:n) indicating position of tab stops to use when converting tabs to spaces. If there are more tabs in a line than defined tab stops the last tab stop is re-used. For the purposes of applying tab stops, each input line is considered a line and the character count begins from the beginning of the input line. |
strwrap2_ctl
can convert tabs to spaces, pad strings up to width
, and
hard-break words if single words are wider than width
.
Unlike base::strwrap, both these functions will translate any non-ASCII strings to UTF-8 and return them in UTF-8. Additionally, malformed UTF-8 sequences are not converted to a text representation of bytes.
When replacing tabs with spaces the tabs are computed relative to the
beginning of the input line, not the most recent wrap point.
Additionally,indent
, exdent
, initial
, and prefix
will be ignored when
computing tab positions.
Non-ASCII strings are converted to and returned in UTF-8 encoding. Width calculations will not work correctly with R < 3.2.2.
fansi for details on how Control Sequences are interpreted, particularly if you are getting unexpected results.
hello.1 <- "hello \033[41mred\033[49m world" hello.2 <- "hello\t\033[41mred\033[49m\tworld" strwrap_ctl(hello.1, 12) strwrap_ctl(hello.2, 12) ## In default mode strwrap2_ctl is the same as strwrap_ctl strwrap2_ctl(hello.2, 12) ## But you can leave whitespace unchanged, `warn` ## set to false as otherwise tabs causes warning strwrap2_ctl(hello.2, 12, strip.spaces=FALSE, warn=FALSE) ## And convert tabs to spaces strwrap2_ctl(hello.2, 12, tabs.as.spaces=TRUE) ## If your display has 8 wide tab stops the following two ## outputs should look the same writeLines(strwrap2_ctl(hello.2, 80, tabs.as.spaces=TRUE)) writeLines(hello.2) ## tab stops are NOT auto-detected, but you may provide ## your own strwrap2_ctl(hello.2, 12, tabs.as.spaces=TRUE, tab.stops=c(6, 12)) ## You can also force padding at the end to equal width writeLines(strwrap2_ctl("hello how are you today", 10, pad.end=".")) ## And a more involved example where we read the ## NEWS file, color it line by line, wrap it to ## 25 width and display some of it in 3 columns ## (works best on displays that support 256 color ## SGR sequences) NEWS <- readLines(file.path(R.home('doc'), 'NEWS')) NEWS.C <- fansi_lines(NEWS, step=2) # color each line W <- strwrap2_ctl(NEWS.C, 25, pad.end=" ", wrap.always=TRUE) writeLines(c("", paste(W[1:20], W[100:120], W[200:220]), ""))