Package fansi. R topics documented: October 5, 2018

Transcription

1 Package fansi October 5, 2018 Title ANSI Control Sequence Aware String Functions Counterparts to R string manipulation functions that account for the effects of ANSI text formatting control sequences. Version Depends R (>= 3.1.0) License GPL (>= 2) LazyData true URL BugReports VignetteBuilder knitr Suggests unitizer, knitr, rmarkdown RoxygenNote Encoding UTF-8 Collate 'constants.r' 'fansi-package.r' 'has.r' 'internal.r' 'load.r' 'misc.r' 'nchar.r' 'strip.r' 'strwrap.r' 'strtrim.r' 'strsplit.r' 'substr2.r' 'tohtml.r' 'unhandled.r' NeedsCompilation yes Author Brodie Gaslam [aut, cre], Elliott Sales De Andrade [ctb], R Core Team [cph] (UTF8 byte length calcs from src/util.c) Maintainer Brodie Gaslam <brodie.gaslam@yahoo.com> Repository CRAN Date/Publication :10:12 UTC R topics documented: fansi fansi_lines has_ctl

2 2 fansi html_code_block html_esc nchar_ctl set_knit_hooks sgr_to_html strip_ctl strsplit_ctl strtrim_ctl strwrap_ctl substr_ctl tabs_as_spaces term_cap_test unhandled_ctl Index 29 fansi Details About Manipulation of Strings Containing Control Sequences Counterparts to R string manipulation functions that account for the effects of ANSI text formatting control sequences. Control Characters and Sequences Control characters and sequences are non-printing inline characters that can be used to modify terminal display and behavior, for example by changing text color or cursor position. We will refer to ANSI control characters and sequences as "Control Sequences" hereafter. There are three types of Control Sequences that fansi can treat specially: "C0" control characters, such as tabs and carriage returns (we include delete in this set, even though technically it is not part of it). Sequences starting in "ESC[", also known as ANSI CSI sequences. Sequences starting in "ESC" and followed by something other than "[". Control Sequences starting with ESC are assumed to be two characters long (including the ESC) unless they are of the CSI variety, in which case their length is computed as per the ECMA-48 specification. There are non-csi escape sequences that may be longer than two characters, but fansi will (incorrectly) treat them as if they were two characters long. In theory it is possible to encode Control Sequences with a single byte introducing character in the 0x40-0x5F range instead of the traditional "ESC[". Since this is rare and it conflicts with UTF-8 encoding, we do not support it. The special treatment of Control Sequences is to compute 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 as needed. Whether a particular type of Control Sequence is treated specially can be specified via the ctl parameter to the fansi functions that have it.

3 fansi 3 ANSI CSI SGR Control Sequences NOTE: not all displays support ANSI CSI SGR sequences; run term_cap_test to see whether your display supports them. ANSI CSI SGR Control Sequences are the subset of CSI sequences that can be used to change text appearance (e.g. color). These sequences begin with "ESC[" and end in "m". fansi interprets these sequences and writes new ones to the output strings in such a way that the original formatting is preserved. In most cases this should be transparent to the user. Occasionally there may be mismatches between how fansi and a display interpret the CSI SGR sequences, which may produce display artifacts. The most likely source of artifacts are Control Sequences that move the cursor or change the display, or that fansi otherwise fails to interpret, such as: Unknown SGR substrings. "C0" control characters like tabs and carriage returns. Other escape sequences. Another possible source of problems is that different displays parse and interpret control sequences differently. The common CSI SGR sequences that you are likely to encounter in formatted text tend to be treated consistently, but less common ones are not. fansi tries to hew by the ECMA-48 specification for CSI control sequences, but not all terminals do. The most likely source of problems will be 24-bit CSI SGR sequences. For example, a 24-bit color sequence such as "ESC[38;2;31;42;4" is a single foreground color to a terminal that supports it, or separate foreground, background, faint, and underline specifications for one that does not. To mitigate this particular problem you can tell fansi what your terminal capabilities are via the term.cap parameter or the "fansi.term.cap" global option, although fansi does try to detect them by default. fansi will will warn if it encounters Control Sequences that it cannot interpret or that might conflict with terminal capabilities. You can turn off warnings via the warn parameter or via the "fansi.warn" global option. fansi can work around "C0" tab control characters by turning them into spaces first with tabs_as_spaces or with the tabs.as.spaces parameter available in some of the fansi functions. We chose to interpret ANSI CSI SGR sequences because this reduces how much string transcription we need to do during string manipulation. If we do not interpret the sequences then we need to record all of them from the beginning of the string and prepend all the accumulated tags up to beginning of a substring to the substring. In many case the bulk of those accumulated tags will be irrelevant as their effects will have been superseded by subsequent tags. fansi assumes that ANSI CSI SGR sequences should be interpreted in cumulative "Graphic Rendition Combination Mode". This means new SGR sequences add to rather than replace previous ones, although in some cases the effect is the same as replacement (e.g. if you have a color active and pick another one). Encodings / UTF-8 fansi will convert any non-ascii strings to UTF-8 before processing them, and fansi functions that return strings will return them encoded in UTF-8. In some cases this will be different to what base R does. For example, substr re-encodes substrings to their original encoding.

4 4 fansi Interpretation of UTF-8 strings is intended to be consistent with base R. There are three ways things may not work out exactly as desired: 1. fansi, despite its best intentions, handles a UTF-8 sequence differently to the way R does. 2. R incorrectly handles a UTF-8 sequence. 3. Your display incorrectly handles a UTF-8 sequence. These issues are most likely to occur with invalid UTF-8 sequences, combining character sequences, and emoji. For example, as of this writing R (and the OSX terminal) consider emojis to be one wide characters, when in reality they are two wide. Do not expect the fansi width calculations to to work correctly with strings containing emoji. Internally, fansi computes the width of every UTF-8 character sequence outside of the ASCII range using the native R_nchar function. This will cause such characters to be processed slower than ASCII characters. Additionally, fansi character width computations can differ from R width computations despite the use of R_nchar. fansi always computes width for each character individually, which assumes that the sum of the widths of each character is equal to the width of a sequence. However, it is theoretically possible for a character sequence that forms a single grapheme to break that assumption. In informal testing we have found this to be rare because in the most common multi-character graphemes the trailing characters are computed as zero width. As of R substr appears to use UTF-8 character byte sizes as indicated by the leading byte, irrespective of whether the subsequent bytes lead to a valid sequence. Additionally, UTF-8 byte sequences as long as 5 or 6 bytes may be allowed, which is likely a holdover from older Unicode versions. fansi mimics this behavior. It is likely substr will start failing with invalid UTF-8 byte sequences with R (as per SVN r74488). In general, you should assume that fansi may not replicate base R exactly when there are illegal UTF-8 sequences present. Our long term objective is to implement proper UTF-8 character width computations, but for simplicity and also because R and our terminal do not do it properly either we are deferring the issue for now. R < support Nominally you can build and run this package in R versions between and Things should mostly work, but please be aware we do not run the test suite under versions of R less than One key degraded capability is width computation of wide-display characters. Under R < fansi will assume every character is 1 display width. Additionally, fansi may not always report malformed UTF-8 sequences as it usually does. One exception to this is nchar_ctl as that is just a thin wrapper around base::nchar. Miscellaneous The native code in this package assumes that all strings are NULL terminated and no longer than (32 bit) INT_MAX (excluding the NULL). This should be a safe assumption since the code is designed to work with STRSXPs and CHRSXPs. Behavior is undefined and probably bad if you somehow manage to provide to fansi strings that do not adhere to these assumptions.

5 fansi_lines 5 fansi_lines Colorize Character Vectors Color each element in input with one of the "256 color" ANSI CSI SGR codes. This is intended for testing and demo purposes. fansi_lines(txt, step = 1) Arguments txt step character vector or object that can be coerced to character vector integer(1l) how quickly to step through the color palette Value character vector with each element colored NEWS <- readlines(file.path(r.home('doc'), 'NEWS')) writelines(fansi_lines(news[1:20])) writelines(fansi_lines(news[1:20], step=8)) has_ctl Checks for Presence of Control Sequences has_ctl checks for any Control Sequence, whereas has_sgr checks only for ANSI CSI SGR sequences. You can check for different types of sequences with the ctl parameter. has_ctl(x, ctl = "all", warn = getoption("fansi.warn"), which) has_sgr(x, warn = getoption("fansi.warn"))

6 6 has_ctl Arguments x ctl warn which a character vector or object that can be coerced to character. character, which Control Sequences should be treated specially. See the "_ctl vs. _sgr" section for details. "nl": newlines. "c0": all other "C0" control characters (i.e. 0x01-0x1f, 0x7F), except for newlines and the actual ESC (0x1B) character. "sgr": ANSI CSI SGR sequences. "csi": all non-sgr ANSI CSI sequences. "esc": all other escape sequences. "all": all of the above, except when used in combination with any of the above, in which case it means "all but". TRUE (default) or FALSE, whether to warn when potentially problematic Control Sequences are encountered. These could cause the assumptions fansi makes about how strings are rendered on your display to be incorrect, for example by moving the cursor (see fansi). character, deprecated in favor of ctl. Value logical of same length as x; NA values in x result in NA values in return _ctl vs. _sgr 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". See Also fansi for details on how Control Sequences are interpreted, particularly if you are getting unexpected results. has_ctl("hello world") has_ctl("hello\nworld") has_ctl("hello\nworld", "sgr") has_ctl("hello\033[31mworld\033[m", "sgr") has_sgr("hello\033[31mworld\033[m") has_sgr("hello\nworld")

7 html_code_block 7 html_code_block Format Character Vector for Display as Code in HTML This simulates what rmarkdown / knitr do to the output of an R markdown chunk, at least as of rmarkdown It is useful when we override the knitr output hooks so that we can have a result that still looks as if it was run by knitr. html_code_block(x, class = "fansi-output") Arguments x class character vector character vectors of classes to apply to the PRE HTML tags. It is the users responsibility to ensure the classes are valid CSS class names. Value character(1l) x, with <PRE> and <CODE> HTML tags applied and collapsed into one line with newlines as the line separator. html_code_block(c("hello world")) html_code_block(c("hello world"), class="pretty") html_esc Escape Characters With Special HTML Meaning This allows displaying strings that contain them in HTML without disrupting the HTML. It is assumed that the string to be escaped does not contain actual HTML as this function would destroy it. html_esc(x) Arguments x character vector

8 8 nchar_ctl Value character vector consisting of x, but with the "<", ">", and "&" characters replaced by their HTML entity codes. html_esc("day > night") html_esc("<span>hello world</span>") nchar_ctl ANSI Control Sequence Aware Version of nchar nchar_ctl counts all non Control Sequence characters. nzchar_ctl returns TRUE for each input vector element that has non Control Sequence sequence characters. By default newlines and other C0 control characters are not counted. nchar_ctl(x, type = "chars", allowna = FALSE, keepna = NA, ctl = "all", warn = getoption("fansi.warn"), strip) nchar_sgr(x, type = "chars", allowna = FALSE, keepna = NA, warn = getoption("fansi.warn")) nzchar_ctl(x, keepna = NA, ctl = "all", warn = getoption("fansi.warn")) nzchar_sgr(x, keepna = NA, warn = getoption("fansi.warn")) Arguments x type allowna keepna ctl a character vector or object that can be coerced to character. character string, one of "chars", or "width". For byte counts use base::nchar. logical: should NA be returned for invalid multibyte strings or "bytes"-encoded strings (rather than throwing an error)? logical: should NA be returned where ever x is NA? If false, nchar() returns 2, as that is the number of printing characters used when strings are written to output, and nzchar() is TRUE. The default for nchar(), NA, means to use keepna = TRUE unless type is "width". Used to be (implicitly) hard coded to FALSE in R versions character, which Control Sequences should be treated specially. See the "_ctl vs. _sgr" section for details. "nl": newlines.

9 nchar_ctl 9 warn strip "c0": all other "C0" control characters (i.e. 0x01-0x1f, 0x7F), except for newlines and the actual ESC (0x1B) character. "sgr": ANSI CSI SGR sequences. "csi": all non-sgr ANSI CSI sequences. "esc": all other escape sequences. "all": all of the above, except when used in combination with any of the above, in which case it means "all but". TRUE (default) or FALSE, whether to warn when potentially problematic Control Sequences are encountered. These could cause the assumptions fansi makes about how strings are rendered on your display to be incorrect, for example by moving the cursor (see fansi). deprecated in favor of ctl. Details nchar_ctl is just a wrapper around nchar(strip_ctl(...)). nzchar_ctl is implemented in native code and is much faster than the otherwise equivalent nzchar(strip_ctl(...)). These functions will warn if either malformed or non-csi escape sequences are encountered, as these may be incorrectly interpreted. _ctl vs. _sgr Note 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". See Also the keepna parameter is ignored for R < fansi for details on how Control Sequences are interpreted, particularly if you are getting unexpected results, strip_ctl for removing Control Sequences. nchar_ctl("\033[31m123\a\r") ## with some wide characters cn.string <- sprintf("\033[31m%s\a\r", "\u4e00\u4e01\u4e03") nchar_ctl(cn.string) nchar_ctl(cn.string, type='width') ## Remember newlines are not counted by default

10 10 set_knit_hooks nchar_ctl("\t\n\r") ## The 'c0' value for the ctl argument does ## not include newlines. nchar_ctl("\t\n\r", ctl="c0") nchar_ctl("\t\n\r", ctl=c("c0", "nl")) ## The _sgr flavor only treats SGR sequences as zero width nchar_sgr("\033[31m123") nchar_sgr("\t\n\n123") ## All of the following are Control Sequences nzchar_ctl("\n\033[42;31m\033[123p\a") set_knit_hooks Set an Output Hook to Display ANSI CSI SGR in Rmarkdown This is a convenience function designed for use within an rmarkdown document. It overrides the knitr output hooks by using knitr::knit_hooks$set. It replaces the hooks with ones that convert ANSI CSI SGR sequences into HTML. In addition to replacing the hook functions, this will output a <STYLE> HTML block to stdout. These two actions are side effects as a result of which R chunks in the rmarkdown document that contain ANSI CSI SGR are shown in their HTML equivalent form. set_knit_hooks(hooks, which = "output", proc.fun = function(x, class) html_code_block(sgr_to_html(html_esc(x)), class = class), class = sprintf("fansi fansi-%s", which), style = getoption("fansi.css"),.test = FALSE) Arguments hooks which proc.fun class list, this should the be knitr::knit_hooks object; we require you pass this to avoid a run-time dependency on knitr. character vector with the names of the hooks that should be replaced, defaults to output, but can also contain values message, warning, and error. function that will be applied to output that contains ANSI CSI SGR sequences. Should accept parameters x and class, where x is the output, and class is the CSS class that should be applied to the <PRE><CODE> blocks the output will be placed in. character the CSS class to give the output chunks. Each type of output chunk specified in which will be matched position-wise to the classes specified here. This vector should be the same length as which.

11 set_knit_hooks 11 style.test character a vector of CSS styles; these will be output inside HTML <STYLE> tags as a side effect. The default value is designed to ensure that there is no visible gap in background color with lines with height 1.5 (as is the default setting in rmarkdown documents v1.1). TRUE or FALSE, for internal testing use only. Details Value Note The replacement hook function tests for the presence of ANSI CSI SGR sequences in chunk output with has_sgr, and if it is detected then processes it with the user provided proc.fun. Chunks that do not contain ANSI CSI SGR are passed off to the previously set hook function. The default proc.fun will run the output through html_esc, sgr_to_html, and finally html_code_block. If you require more control than this function provides you can set the knitr hooks manually with knitr::knit_hooks$set. named list with the prior output hooks for each of which. Since we do not formally import the knitr functions we do not guarantee that this function will always work properly with knitr / rmarkdown. See Also has_sgr, sgr_to_html, html_esc, html_code_block, knitr output hooks, embedding CSS in Rmd. ## Not run: ## The following should be done within an rmarkdown document chunk with ## chunk option results set to 'asis' and the chunk option comment set ## to ''. {r comment="", results='asis', echo=false} ## Change the "output" hook to handle ANSI CSI SGR old.hooks <- set_knit_hooks(knitr::knit_hooks) ## Do the same with the warning, error, and message, and add styles for ## them (alternatively we could have done output as part of this call too) styles <- c( getoption('fansi.style'), # default style "PRE.fansi CODE {background-color: transparent;}", "PRE.fansi-error {background-color: #DD5555;}", "PRE.fansi-warning {background-color: #DDDD55;}", "PRE.fansi-message {background-color: #EEEEEE;}" )

12 12 sgr_to_html old.hooks <- c( old.hooks, fansi::set_knit_hooks( knitr::knit_hooks, which=c('warning', 'error', 'message'), style=styles ) ) ## You may restore old hooks with the following chunk ## Restore Hooks {r} do.call(knitr::knit_hooks$set, old.hooks) ## End(Not run) sgr_to_html Convert ANSI CSI SGR Escape Sequence to HTML Equivalents Only the colors, background-colors, and basic styles (CSI SGR codes 1-9) are translated. Others are dropped silently. sgr_to_html(x, warn = getoption("fansi.warn"), term.cap = getoption("fansi.term.cap")) Arguments x warn term.cap a character vector or object that can be coerced to character. TRUE (default) or FALSE, whether to warn when potentially problematic Control Sequences are encountered. These could cause the assumptions fansi makes about how strings are rendered on your display to be incorrect, for example by moving the cursor (see fansi). character a vector of the capabilities of the terminal, can be any combination "bright" (SGR codes 90-97, ), "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 fansi interprets escape sequences, so you should ensure that it matches your terminal capabilities. See term_cap_test for details. Value a character vector with all escape sequences removed and any basic ANSI CSI SGR escape sequences applied via SPAN html objects with inline css styles.

13 strip_ctl 13 Note See Also 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. sgr_to_html("hello\033[31;42;1mworld\033[m") strip_ctl Strip ANSI Control Sequences Removes Control Sequences from strings. By default it will strip all known Control Sequences, including ANSI CSI sequences, two character sequences starting with ESC, and all C0 control characters, including newlines. You can fine tune this behavior with the ctl parameter. strip_sgr only strips ANSI CSI SGR sequences. strip_ctl(x, ctl = "all", warn = getoption("fansi.warn"), strip) strip_sgr(x, warn = getoption("fansi.warn")) Arguments x ctl warn strip a character vector or object that can be coerced to character. character, any combination of the following values (see details): "nl": strip newlines. "c0": strip all other "C0" control characters (i.e. x01-x1f, x7f), except for newlines and the actual ESC character. "sgr": strip ANSI CSI SGR sequences. "csi": strip all non-sgr csi sequences. "esc": strip all other escape sequences. "all": all of the above, except when used in combination with any of the above, in which case it means "all but" (see details). TRUE (default) or FALSE, whether to warn when potentially problematic Control Sequences are encountered. These could cause the assumptions fansi makes about how strings are rendered on your display to be incorrect, for example by moving the cursor (see fansi). character, deprecated in favor of ctl.

14 14 strip_ctl Details The ctl value contains the names of non-overlapping subsets of the known Control Sequences (e.g. "csi" does not contain "sgr", and "c0" does not contain newlines). The one exception is "all" which means strip every known sequence. If you combine "all" with any other option then everything but that option will be stripped. Value character vector of same length as x with ANSI escape sequences stripped _ctl vs. _sgr 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". Note Non-ASCII strings are converted to and returned in UTF-8 encoding. See Also fansi for details on how Control Sequences are interpreted, particularly if you are getting unexpected results. string <- "hello\033k\033[45p world\n\033[31mgoodbye\a moon" strip_ctl(string) strip_ctl(string, c("nl", "c0", "sgr", "csi", "esc")) # equivalently strip_ctl(string, "sgr") strip_ctl(string, c("c0", "esc")) ## everything but C0 controls, we need to specify "nl" ## in addition to "c0" since "nl" is not part of "c0" ## as far as the strip argument is concerned strip_ctl(string, c("all", "nl", "c0")) ## convenience function, same as strip_ctl(ctl='sgr') strip_sgr(string)

15 strsplit_ctl 15 strsplit_ctl ANSI Control Sequence Aware Version of strsplit A drop-in replacement for base::strsplit. It will be noticeably slower, but should otherwise behave the same way except for Control Sequence awareness. strsplit_ctl(x, split, fixed = FALSE, perl = FALSE, usebytes = FALSE, warn = getoption("fansi.warn"), term.cap = getoption("fansi.term.cap"), ctl = "all") strsplit_sgr(x, split, fixed = FALSE, perl = FALSE, usebytes = FALSE, warn = getoption("fansi.warn"), term.cap = getoption("fansi.term.cap")) Arguments x split fixed perl usebytes warn term.cap ctl a character vector, or, unlike base::strsplit an object that can be coerced to character. character vector (or object which can be coerced to such) containing regular expression(s) (unless fixed = TRUE) to use for splitting. If empty matches occur, in particular if split has length 0, x is split into single characters. If split has length greater than 1, it is re-cycled along x. logical. If TRUE match split exactly, otherwise use regular expressions. Has priority over perl. logical. Should Perl-compatible regexps be used? logical. If TRUE the matching is done byte-by-byte rather than character-bycharacter, and inputs with marked encodings are not converted. This is forced (with a warning) if any input is found which is marked as "bytes" (see Encoding). TRUE (default) or FALSE, whether to warn when potentially problematic Control Sequences are encountered. These could cause the assumptions fansi makes about how strings are rendered on your display to be incorrect, for example by moving the cursor (see fansi). character a vector of the capabilities of the terminal, can be any combination "bright" (SGR codes 90-97, ), "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 fansi interprets escape sequences, so you should ensure that it matches your terminal capabilities. See term_cap_test for details. character, which Control Sequences should be treated specially. See the "_ctl vs. _sgr" section for details. "nl": newlines.

16 16 strsplit_ctl Details Value "c0": all other "C0" control characters (i.e. 0x01-0x1f, 0x7F), except for newlines and the actual ESC (0x1B) character. "sgr": ANSI CSI SGR sequences. "csi": all non-sgr ANSI CSI sequences. "esc": all other escape sequences. "all": all of the above, except when used in combination with any of the above, in which case it means "all but". This function works by computing the position of the split points after removing Control Sequences, and uses those positions in conjunction with substr_ctl to extract the pieces. An important implication of this is that you cannot split by Control Sequences that are being treated as Control Sequences. You can however limit which control sequences are treated specially via the ctl parameters (see examples). list, see base::strsplit. _ctl vs. _sgr Note 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. The split positions are computed after both x and split are converted to UTF-8. See Also fansi for details on how Control Sequences are interpreted, particularly if you are getting unexpected results, base::strsplit for details on the splitting. strsplit_sgr("\033[31mhello\033[42m world!", " ") ## Next two examples allow splitting by newlines, which ## normally doesn't work as newlines are _Control Sequences_ strsplit_sgr("\033[31mhello\033[42m\nworld!", "\n") strsplit_ctl("\033[31mhello\033[42m\nworld!", "\n", ctl=c("all", "nl"))

17 strtrim_ctl 17 strtrim_ctl ANSI Control Sequence Aware Version of strtrim One difference with base::strtrim is that all C0 control characters such as newlines, carriage returns, etc., are treated as zero width. strtrim_ctl(x, width, warn = getoption("fansi.warn"), ctl = "all") strtrim2_ctl(x, width, warn = getoption("fansi.warn"), tabs.as.spaces = getoption("fansi.tabs.as.spaces"), tab.stops = getoption("fansi.tab.stops"), ctl = "all") strtrim_sgr(x, width, warn = getoption("fansi.warn")) strtrim2_sgr(x, width, warn = getoption("fansi.warn"), tabs.as.spaces = getoption("fansi.tabs.as.spaces"), tab.stops = getoption("fansi.tab.stops")) Arguments x a character vector, or an object which can be coerced to a character vector by as.character. width Positive integer values: recycled to the length of x. warn ctl TRUE (default) or FALSE, whether to warn when potentially problematic Control Sequences are encountered. These could cause the assumptions fansi makes about how strings are rendered on your display to be incorrect, for example by moving the cursor (see fansi). character, which Control Sequences should be treated specially. See the "_ctl vs. _sgr" section for details. "nl": newlines. "c0": all other "C0" control characters (i.e. 0x01-0x1f, 0x7F), except for newlines and the actual ESC (0x1B) character. "sgr": ANSI CSI SGR sequences. "csi": all non-sgr ANSI CSI sequences. "esc": all other escape sequences. "all": all of the above, except when used in combination with any of the above, in which case it means "all but". tabs.as.spaces FALSE (default) or TRUE, whether to convert tabs to spaces. This can only be set to TRUE if strip.spaces is FALSE.

18 18 strwrap_ctl 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. Details strtrim2_ctl adds the option of converting tabs to spaces before trimming. This is the only difference between strtrim_ctl and strtrim2_ctl. _ctl vs. _sgr 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". Note Non-ASCII strings are converted to and returned in UTF-8 encoding. Width calculations will not work correctly with R < See Also fansi for details on how Control Sequences are interpreted, particularly if you are getting unexpected results. strwrap_ctl is used internally by this function. strtrim_ctl("\033[42mhello world\033[m", 6) strwrap_ctl ANSI Control Sequence Aware Version of strwrap 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.

19 strwrap_ctl 19 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")) Arguments x width indent exdent prefix simplify initial warn a character vector, or an object which can be converted to a character vector by as.character. 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 initial is used. a logical. If TRUE, the result is a single character vector of line text; otherwise, it is a list of the same length as x the elements of which are character vectors of line text obtained from the corresponding element of x. (Hence, the result in the former case is obtained by unlisting that of the latter.) a character string to be used as prefix for each line except the first, for which initial is used. TRUE (default) or FALSE, whether to warn when potentially problematic Control Sequences are encountered. These could cause the assumptions fansi makes about how strings are rendered on your display to be incorrect, for example by moving the cursor (see fansi).

20 20 strwrap_ctl term.cap ctl Details wrap.always pad.end strip.spaces character a vector of the capabilities of the terminal, can be any combination "bright" (SGR codes 90-97, ), "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 fansi interprets escape sequences, so you should ensure that it matches your terminal capabilities. See term_cap_test for details. character, which Control Sequences should be treated specially. See the "_ctl vs. _sgr" section for details. "nl": newlines. "c0": all other "C0" control characters (i.e. 0x01-0x1f, 0x7F), except for newlines and the actual ESC (0x1B) character. "sgr": ANSI CSI SGR sequences. "csi": all non-sgr ANSI CSI sequences. "esc": all other escape sequences. "all": all of the above, except when used in combination with any of the above, in which case it means "all but". 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 width must be at least 2. character(1l), a single character to use as padding at the end of each line until the line is width wide. This must be a printable ASCII character or an empty string (default). If you set it to an empty string the line remains unpadded. 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 strip.spaces is FALSE. 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. _ctl vs. _sgr 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

21 strwrap_ctl 21 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". Note Non-ASCII strings are converted to and returned in UTF-8 encoding. Width calculations will not work correctly with R < See Also 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)

22 22 substr_ctl 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]), "")) substr_ctl ANSI Control Sequence Aware Version of substr substr_ctl is a drop-in replacement for substr. Performance is slightly slower than substr. ANSI CSI SGR sequences will be included in the substrings to reflect the format of the substring when it was embedded in the source string. Additionally, other Control Sequences specified in ctl are treated as zero-width. substr_ctl(x, start, stop, warn = getoption("fansi.warn"), term.cap = getoption("fansi.term.cap"), ctl = "all") substr2_ctl(x, start, stop, type = "chars", round = "start", 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") substr_sgr(x, start, stop, warn = getoption("fansi.warn"), term.cap = getoption("fansi.term.cap")) substr2_sgr(x, start, stop, type = "chars", round = "start", tabs.as.spaces = getoption("fansi.tabs.as.spaces"), tab.stops = getoption("fansi.tab.stops"), warn = getoption("fansi.warn"), term.cap = getoption("fansi.term.cap")) Arguments x start stop warn a character vector or object that can be coerced to character. integer. The first element to be replaced. integer. The last element to be replaced. TRUE (default) or FALSE, whether to warn when potentially problematic Control Sequences are encountered. These could cause the assumptions fansi makes about how strings are rendered on your display to be incorrect, for example by moving the cursor (see fansi).

23 substr_ctl 23 term.cap ctl type Details round character a vector of the capabilities of the terminal, can be any combination "bright" (SGR codes 90-97, ), "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 fansi interprets escape sequences, so you should ensure that it matches your terminal capabilities. See term_cap_test for details. character, which Control Sequences should be treated specially. See the "_ctl vs. _sgr" section for details. "nl": newlines. "c0": all other "C0" control characters (i.e. 0x01-0x1f, 0x7F), except for newlines and the actual ESC (0x1B) character. "sgr": ANSI CSI SGR sequences. "csi": all non-sgr ANSI CSI sequences. "esc": all other escape sequences. "all": all of the above, except when used in combination with any of the above, in which case it means "all but". character(1l) partial matching c("chars", "width"), although type="width" only works correctly with R >= character(1l) partial matching c("start", "stop", "both", "neither"), controls how to resolve ambiguities when a start or stop value in "width" type mode falls within a multi-byte character or a wide display character. See details. tabs.as.spaces FALSE (default) or TRUE, whether to convert tabs to spaces. This can only be set to TRUE if strip.spaces is FALSE. 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. substr2_ctl and substr2_sgr add the ability to retrieve substrings based on display width, and byte width in addition to the normal character width. substr2_ctl also provides the option to convert tabs to spaces with tabs_as_spaces prior to taking substrings. Because exact substrings on anything other than character width cannot be guaranteed (e.g. as a result of multi-byte encodings, or double display-width characters) substr2_ctl must make assumptions on how to resolve provided start/stop values that are infeasible and does so via the round parameter. If we use "start" as the round value, then any time the start value corresponds to the middle of a multi-byte or a wide character, then that character is included in the substring, while any similar partially included character via the stop is left out. The converse is true if we use "stop" as the round value. "neither" would cause all partial characters to be dropped irrespective whether they correspond to start or stop, and "both" could cause all of them to be included. _ctl vs. _sgr 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

24 24 tabs_as_spaces 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". Note Non-ASCII strings are converted to and returned in UTF-8 encoding. See Also fansi for details on how Control Sequences are interpreted, particularly if you are getting unexpected results. substr_ctl("\033[42mhello\033[m world", 1, 9) substr_ctl("\033[42mhello\033[m world", 3, 9) ## Width 2 and 3 are in the middle of an ideogram as ## start and stop positions respectively, so we control ## what we get with round cn.string <- paste0("\033[42m", "\u4e00\u4e01\u4e03", "\033[m") substr2_ctl(cn.string, 2, 3, type='width') substr2_ctl(cn.string, 2, 3, type='width', round='both') substr2_ctl(cn.string, 2, 3, type='width', round='start') substr2_ctl(cn.string, 2, 3, type='width', round='stop') ## the _sgr variety only treat as special CSI SGR, ## compare the following: substr_sgr("\033[31mhello\tworld", 1, 6) substr_ctl("\033[31mhello\tworld", 1, 6) substr_ctl("\033[31mhello\tworld", 1, 6, ctl=c('all', 'c0')) tabs_as_spaces Replace Tabs With Spaces Finds horizontal tab characters (0x09) in a string and replaces them with the spaces that produce the same horizontal offset.

25 tabs_as_spaces 25 tabs_as_spaces(x, tab.stops = getoption("fansi.tab.stops"), warn = getoption("fansi.warn"), ctl = "all") Arguments x tab.stops warn ctl character vector or object coercible to character; any tabs therein will be replaced. 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. TRUE (default) or FALSE, whether to warn when potentially problematic Control Sequences are encountered. These could cause the assumptions fansi makes about how strings are rendered on your display to be incorrect, for example by moving the cursor (see fansi). character, which Control Sequences should be treated specially. See the "_ctl vs. _sgr" section for details. "nl": newlines. "c0": all other "C0" control characters (i.e. 0x01-0x1f, 0x7F), except for newlines and the actual ESC (0x1B) character. "sgr": ANSI CSI SGR sequences. "csi": all non-sgr ANSI CSI sequences. "esc": all other escape sequences. "all": all of the above, except when used in combination with any of the above, in which case it means "all but". Details Value Note Since we do not know of a reliable cross platform means of detecting tab stops you will need to provide them yourself if you are using anything outside of the standard tab stop every 8 characters that is the default. character, x with tabs replaced by spaces, with elements possibly converted to UTF-8. Non-ASCII strings are converted to and returned in UTF-8 encoding. The ctl parameter only affects which Control Sequences are considered zero width. Tabs will always be converted to spaces, irrespective of the ctl setting. See Also fansi for details on how Control Sequences are interpreted, particularly if you are getting unexpected results.

26 26 term_cap_test string <- '1\t12\t123\t1234\t ' tabs_as_spaces(string) writelines( c( ' ', tabs_as_spaces(string) ) ) writelines( c( ' ', tabs_as_spaces(string, tab.stops=c(2, 3)) ) ) writelines( c( ' ', tabs_as_spaces(string, tab.stops=c(2, 3, 8)) ) ) term_cap_test Test Terminal Capabilities Details Outputs ANSI CSI SGR formatted text to screen so that you may visually inspect what color capabilities your terminal supports. term_cap_test() The three tested terminal capabilities are: "bright" for bright colors with SGR codes in and "256" for colors defined by "38;5;x" and "48;5;x" where x is in "truecolor" for colors defined by "38;2;x;y;z" and "48;x;y;x" where x, y, and z are in Each of the color capabilities your terminal supports should be displayed with a blue background and a red foreground. For reference the corresponding CSI SGR sequences are displayed as well. You should compare the screen output from this function to getoption('fansi.term.cap') to ensure that they are self consistent. By default fansi assumes terminals support bright and 256 color modes, and also tests for truecolor support via the $COLORTERM system variable. Functions with the term.cap parameter like substr_ctl will warn if they encounter 256 or true color SGR sequences and term.cap indicates they are unsupported as such a terminal may misinterpret those sequences. Bright codes in terminals that do not support them are more likely to be silently ignored, so fansi functions do not warn about those.