ANSI Control Sequence Aware String Functions
Counterparts to R string manipulation functions that account for
the effects of ANSI text formatting control sequences.
fansi - ANSI Control Sequence Aware String Functions
Counterparts to R string manipulation functions that account for the effects of ANSI text formatting control sequences.
Formatting Strings with Control Sequences
Many terminals will recognize special sequences of characters in strings and
change display behavior as a result. For example, on my terminal the sequence
"\033[42m" turns text background green:
The sequence itself is not shown, but the text display changes.
This type of sequence is called an ANSI CSI SGR control sequence. Most *nix
terminals support them, and newer versions of Windows and Rstudio consoles do
too. You can check whether your display supports them by running
fansi functions behave as expected depends on many factors,
including how your particular display handles Control Sequences. See
for details, particularly if you are getting unexpected results.
Control Sequences Require Special Handling
ANSI control characters and sequences (Control Sequences hereafter) break the relationship between byte/character position in a string and display position.
For example, in
"Hello \033[42mWorld, Good\033[m Night Moon!" the space
after "World," is thirteenth displayed character, but the eighteenth actual
character ("\033" is a single character, the ESC). If we try to split the
string after the space with
substr things go wrong in several ways:
We end up cutting up our string in the middle of "World", and worse the
formatting bleeds out of our string into the prompt line. Compare to what
happens when we use
substr_ctl, the Control Sequence aware version of
fansi provides counterparts to the following string functions:
These are drop-in replacements that behave (almost) identically to the base counterparts, except for the Control Sequence awareness.
fansi also includes improved versions of some of those functions, such as
substr2_ctl which allows for width based substrings. There are also
utility functions such as
strip_ctl to remove Control Sequences and
to detect whether strings contain them.
fansi is written in C so you should find performance of the
functions to be comparable to the base functions.
strwrap_ctl is much faster,
strsplit_ctl is somewhat slower than the corresponding base functions.
You can translate ANSI CSI SGR formatted strings into their HTML counterparts
It is possible to set
knitr hooks such that R output that contains ANSI CSI
SGR is automatically converted to the HTML formatted equivalent and displayed as
intended. See the
This package is available on CRAN:
It has no runtime dependencies.
For the development version use:
f.dl <- tempfile() f.uz <- tempfile() github.url <- 'https://github.com/brodieG/fansi/archive/development.zip' download.file(github.url, f.dl) unzip(f.dl, exdir=f.uz) install.packages(file.path(f.uz, 'fansi-development'), repos=NULL, type='source') unlink(c(f.dl, f.uz))
Related Packages and References
- crayon, the library that started it all.
- ansistrings, which implements similar functionality.
- ECMA-48 - Control Functions For Coded Character Sets, in particular pages 10-12, and 61.
- CCITT Recommendation T.416
- ANSI Escape Code - Wikipedia for a gentler introduction.
- R Core for developing and maintaining such a wonderful language.
- CRAN maintainers, for patiently shepherding packages onto CRAN and maintaining the repository, and Uwe Ligges in particular for maintaining Winbuilder.
- Gábor Csárdi for getting me started on the journey ANSI control sequences.
- Jim Hester because covr rocks.
- Dirk Eddelbuettel and Carl Boettiger for the rocker project, and Gábor Csárdi and the R-consortium for Rhub, without which testing bugs on R-devel and other platforms would be a nightmare.
- Tomas Kalibera for rchk and the accompanying vagrant image, and rcnst to help detect errors in compiled code.
- Winston Chang for the r-debug docker container, in particular because of the valgrind level 2 instrumented version of R.
- Hadley Wickham for devtools and roxygen2.
- Yihui Xie for knitr and J.J. Allaire etal for rmarkdown, and by extension John MacFarlane for pandoc.
- Olaf Mersmann for microbenchmark, because microsecond matter.
- All open source developers out there that make their work freely available for others to use.
- Github, Travis-CI, Codecov, Vagrant, Docker, Ubuntu, Brew for providing infrastructure that greatly simplifies open source development.
- Free Software Foundation for developing the GPL license and promotion of the free software movement.
Functions in fansi
|strwrap_ctl||ANSI Control Sequence Aware Version of strwrap|
|strsplit_ctl||ANSI Control Sequence Aware Version of strsplit|
|substr_ctl||ANSI Control Sequence Aware Version of substr|
|tabs_as_spaces||Replace Tabs With Spaces|
|sgr_to_html||Convert ANSI CSI SGR Escape Sequence to HTML Equivalents|
|unhandled_ctl||Identify Unhandled ANSI Control Sequences|
|html_code_block||Format Character Vector for Display as Code in HTML|
|term_cap_test||Test Terminal Capabilities|
|fansi_lines||Colorize Character Vectors|
|html_esc||Escape Characters With Special HTML Meaning|
|nchar_ctl||ANSI Control Sequence Aware Version of nchar|
|strip_ctl||Strip ANSI Control Sequences|
|has_ctl||Checks for Presence of Control Sequences|
|strtrim_ctl||ANSI Control Sequence Aware Version of strtrim|
|fansi||Details About Manipulation of Strings Containing Control Sequences|
|set_knit_hooks||Set an Output Hook to Display ANSI CSI SGR in Rmarkdown|
Vignettes of fansi
Last month downloads
|License||GPL (>= 2)|
|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'|
|Packaged||2018-08-09 19:30:25 UTC; bg|
|Date/Publication||2018-08-13 14:40:11 UTC|
Include our badge in your README