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"), ctl = "all" ) 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"), ctl = "all" ) strwrap_sgr( 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_sgr( 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 |
ctl |
character, which Control Sequences should be treated specially. See the "_ctl vs. _sgr" section for details.
|
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. When FALSE, whitespaces are preserved, except for newlines as those are implicit in boundaries between vector elements. |
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.
The *_ctl
versions of the functions treat all Control Sequences specially
by default. Special treatment is context dependent, and may include
detecting them and/or computing their display/character width as zero. For
the SGR subset of the ANSI CSI sequences, fansi
will also parse, interpret,
and reapply the text styles they encode if needed. You can modify whether a
Control Sequence is treated specially with the ctl
parameter. You can
exclude a type of Control Sequence from special treatment by combining
"all" with that type of sequence (e.g. ctl=c("all", "nl")
for special
treatment of all Control Sequences but newlines). The *_sgr
versions
only treat ANSI CSI SGR sequences specially, and are equivalent to the
*_ctl
versions with the ctl
parameter set to "sgr".
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]), ""))