1% Generated by roxygen2: do not edit by hand
2% Please edit documentation in R/strip.R
3\name{strip_ctl}
4\alias{strip_ctl}
5\alias{strip_sgr}
6\title{Strip ANSI Control Sequences}
7\usage{
8strip_ctl(x, ctl = "all", warn = getOption("fansi.warn"), strip)
9
10strip_sgr(x, warn = getOption("fansi.warn"))
11}
12\arguments{
13\item{x}{a character vector or object that can be coerced to character.}
14
15\item{ctl}{character, any combination of the following values (see details):
16\itemize{
17\item "nl": strip newlines.
18\item "c0": strip all other "C0" control characters (i.e. x01-x1f, x7F),
19except for newlines and the actual ESC character.
20\item "sgr": strip ANSI CSI SGR sequences.
21\item "csi": strip all non-SGR csi sequences.
22\item "esc": strip all other escape sequences.
23\item "all": all of the above, except when used in combination with any of the
24above, in which case it means "all but" (see details).
25}}
26
27\item{warn}{TRUE (default) or FALSE, whether to warn when potentially
28problematic \emph{Control Sequences} are encountered.  These could cause the
29assumptions \code{fansi} makes about how strings are rendered on your display
30to be incorrect, for example by moving the cursor (see \link{fansi}).}
31
32\item{strip}{character, deprecated in favor of \code{ctl}.}
33}
34\value{
35character vector of same length as x with ANSI escape sequences
36stripped
37}
38\description{
39Removes \emph{Control Sequences} from strings.  By default it will
40strip all known \emph{Control Sequences}, including ANSI CSI
41sequences, two character sequences starting with ESC, and all C0 control
42characters, including newlines.  You can fine tune this behavior with the
43\code{ctl} parameter.  \code{strip_sgr} only strips ANSI CSI SGR sequences.
44}
45\details{
46The \code{ctl} value contains the names of \strong{non-overlapping} subsets of the
47known \emph{Control Sequences} (e.g. "csi" does not contain "sgr", and "c0" does
48not contain newlines).  The one exception is "all" which means strip every
49known sequence.  If you combine "all" with any other option then everything
50\strong{but} that option will be stripped.
51}
52\note{
53Non-ASCII strings are converted to and returned in UTF-8 encoding.
54}
55\section{_ctl vs. _sgr}{
56
57
58The \verb{*_ctl} versions of the functions treat all \emph{Control Sequences} specially
59by default.  Special treatment is context dependent, and may include
60detecting them and/or computing their display/character width as zero.  For
61the SGR subset of the ANSI CSI sequences, \code{fansi} will also parse, interpret,
62and reapply the text styles they encode if needed.  You can modify whether a
63\emph{Control Sequence} is treated specially with the \code{ctl} parameter.  You can
64exclude a type of \emph{Control Sequence} from special treatment by combining
65"all" with that type of sequence (e.g. \code{ctl=c("all", "nl")} for special
66treatment of all \emph{Control Sequences} \strong{but} newlines).  The \verb{*_sgr} versions
67only treat ANSI CSI SGR sequences specially, and are equivalent to the
68\verb{*_ctl} versions with the \code{ctl} parameter set to "sgr".
69}
70
71\examples{
72string <- "hello\033k\033[45p world\n\033[31mgoodbye\a moon"
73strip_ctl(string)
74strip_ctl(string, c("nl", "c0", "sgr", "csi", "esc")) # equivalently
75strip_ctl(string, "sgr")
76strip_ctl(string, c("c0", "esc"))
77
78## everything but C0 controls, we need to specify "nl"
79## in addition to "c0" since "nl" is not part of "c0"
80## as far as the `strip` argument is concerned
81strip_ctl(string, c("all", "nl", "c0"))
82
83## convenience function, same as `strip_ctl(ctl='sgr')`
84strip_sgr(string)
85}
86\seealso{
87\link{fansi} for details on how \emph{Control Sequences} are
88interpreted, particularly if you are getting unexpected results.
89}
90