Wraps strings to a specified width accounting for Control Sequences.
strwrap_ctl is intended to emulate
strwrap closely except with respect to
the Control Sequences (see details for other minor differences), while
strwrap2_ctl adds features and changes the processing of whitespace.
strwrap_ctl is faster than
strwrap_ctl( x, width = 0.9 * getOption("width"), indent = 0, exdent = 0, prefix = "", simplify = TRUE, initial = prefix, warn = getOption("fansi.warn", TRUE), term.cap = getOption("fansi.term.cap", dflt_term_cap()), ctl = "all", normalize = getOption("fansi.normalize", FALSE), carry = getOption("fansi.carry", FALSE), terminate = getOption("fansi.terminate", TRUE) ) 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", FALSE), tab.stops = getOption("fansi.tab.stops", 8L), warn = getOption("fansi.warn", TRUE), term.cap = getOption("fansi.term.cap", dflt_term_cap()), ctl = "all", normalize = getOption("fansi.normalize", FALSE), carry = getOption("fansi.carry", FALSE), terminate = getOption("fansi.terminate", TRUE) )
a character vector, or an object which can be converted to a
character vector by
a positive integer giving the target column for wrapping lines in the output.
a non-negative integer giving the indentation of the first line in a paragraph.
a non-negative integer specifying the indentation of subsequent lines in paragraphs.
a character string to be used as prefix for
each line except the first, for which
a logical. If
TRUE (default) or FALSE, whether to warn when potentially
problematic Control Sequences are encountered. These could cause the
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"), "truecolor" (SGR codes starting with
"38;2" or "48;2"), and "all". "all" behaves as it does for the
character, which Control Sequences should be treated
specially. 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, and OSC hyperlinks,
TRUE or FALSE (default) whether SGR sequence should be
normalized out such that there is one distinct sequence for each SGR code.
normalized strings will occupy more space (e.g. "\033[31;42m" becomes
"\033[31m\033[42m"), but will work better with code that assumes each SGR
code will be in its own escape as
TRUE, FALSE (default), or a scalar string, controls whether to
interpret the character vector as a "single document" (TRUE or string) or
as independent elements (FALSE). In "single document" mode, active state
at the end of an input element is considered active at the beginning of the
next vector element, simulating what happens with a document with active
state at the end of a line. If FALSE each vector element is interpreted as
if there were no active state when it begins. If character, then the
active state at the end of the
TRUE (default) or FALSE whether substrings should have
active state closed to avoid it bleeding into other strings they may be
prepended onto. This does not stop state from carrying if
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
character(1L), a single character to use as padding at the
end of each line until the line is
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 boundaries between output vector elements.
FALSE (default) or TRUE, whether to convert tabs to
spaces. This can only be set to TRUE if
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
hard-break words if single words are wider than
Unlike base::strwrap, both these functions will translate any non-ASCII
strings to UTF-8 and return them in UTF-8. Additionally, invalid UTF-8
always causes errors, and
indent must be scalar.
When replacing tabs with spaces the tabs are computed relative to the
beginning of the input line, not the most recent wrap point.
prefix will be ignored when
computing tab positions.
A character vector, or list of character vectors if
Control Sequences are non-printing characters or sequences of characters.
Special Sequences are a subset of the Control Sequences, and include CSI
SGR sequences which can be used to change rendered appearance of text, and
OSC hyperlinks. See
fansi for details.
fansi approximates grapheme widths and counts by using heuristics for
grapheme breaks that work for most common graphemes, including emoji
combining sequences. The heuristic is known to work incorrectly with
invalid combining sequences, prepending marks, and sequence interruptors.
fansi does not provide a full implementation of grapheme break detection to
avoid carrying a copy of the Unicode grapheme breaks table, and also because
the hope is that R will add the feature eventually itself.
utf8 package provides a
conforming grapheme parsing implementation.
Several factors could affect the exact output produced by
functions across versions of
R, and/or across systems.
In general it is best not to rely on exact
fansi output, e.g. by
embedding it in tests.
Width and grapheme calculations depend on locale, Unicode database
version, and grapheme processing logic (which is still in development), among
other things. For the most part
fansi (currently) uses the internals of
base::nchar(type='width'), but there are exceptions and this may change in
How a particular display format is encoded in Control Sequences is
not guaranteed to be stable across
fansi versions. Additionally, which
Special Sequences are re-encoded vs transcribed untouched may change.
In general we will strive to keep the rendered appearance stable.
To maximize the odds of getting stable output set
"chars" in functions that allow it, and
term.cap to a specific set of capabilities.
fansi is unaware of text directionality and operates as if all strings are
left to right (LTR). Using
fansi function with strings that contain mixed
direction scripts (i.e. both LTR and RTL) may produce undesirable results.
Non-ASCII strings are converted to and returned in UTF-8 encoding. Width calculations will not work properly in R < 3.2.2.
strwrap* functions the
carry parameter affects whether
styles are carried across input vector elements. Styles always carry
within a single wrapped vector element (e.g. if one of the input elements
gets wrapped into three lines, the styles will carry through those three
lines even if
carry=FALSE, but not across input vector elements).
?fansi for details on how Control Sequences are
interpreted, particularly if you are getting unexpected results,
normalize_state for more details on what the
normalize parameter does,
state_at_end to compute active state at the end of strings,
close_state to compute the sequence required to close active state.
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]), ""))
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.