diff --git a/DESCRIPTION b/DESCRIPTION index 3edff008..31871307 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -2,7 +2,7 @@ Package: fansi Title: ANSI Control Sequence Aware String Functions Description: Counterparts to R string manipulation functions that account for the effects of ANSI text formatting control sequences. -Version: 1.0.4 +Version: 1.0.4.9000 Authors@R: c( person("Brodie", "Gaslam", email="brodie.gaslam@yahoo.com", role=c("aut", "cre")), @@ -24,7 +24,7 @@ Suggests: Imports: grDevices, utils -RoxygenNote: 7.1.1 +RoxygenNote: 7.2.3 Roxygen: list(markdown = TRUE, load = "installed") Encoding: UTF-8 Collate: diff --git a/R/fansi-package.R b/R/fansi-package.R index de329ef6..7836055f 100644 --- a/R/fansi-package.R +++ b/R/fansi-package.R @@ -270,6 +270,7 @@ #' #' @useDynLib fansi, .registration=TRUE, .fixes="FANSI_" #' @docType package +#' @aliases fansi-package #' @name fansi NULL diff --git a/R/strsplit.R b/R/strsplit.R index 137e5611..9fd6c441 100644 --- a/R/strsplit.R +++ b/R/strsplit.R @@ -35,6 +35,7 @@ #' @inherit substr_ctl seealso #' @inheritSection substr_ctl Control and Special Sequences #' @inheritSection substr_ctl Output Stability +#' @inheritSection substr_ctl Bidirectional Text #' @note Non-ASCII strings are converted to and returned in UTF-8 encoding. #' Width calculations will not work properly in R < 3.2.2. #' @return Like [`base::strsplit`], with _Control Sequences_ excluded. diff --git a/R/strwrap.R b/R/strwrap.R index 469648ab..b910dc92 100644 --- a/R/strwrap.R +++ b/R/strwrap.R @@ -36,6 +36,7 @@ #' @inheritSection substr_ctl Control and Special Sequences #' @inheritSection substr_ctl Graphemes #' @inheritSection substr_ctl Output Stability +#' @inheritSection substr_ctl Bidirectional Text #' @inheritParams base::strwrap #' @inheritParams tabs_as_spaces #' @inheritParams substr_ctl diff --git a/R/substr2.R b/R/substr2.R index c5b26c47..50e87d56 100644 --- a/R/substr2.R +++ b/R/substr2.R @@ -148,10 +148,15 @@ #' The [`utf8`](https://cran.r-project.org/package=utf8) package provides a #' conforming grapheme parsing implementation. #' +#' @section Bidirectional Text: +#' +#' `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. +#' #' @note Non-ASCII strings are converted to and returned in UTF-8 encoding. #' Width calculations will not work properly in R < 3.2.2. #' @note If `stop` < `start`, the return value is always an empty string. -#' @inheritParams base::substr #' @export #' @seealso [`?fansi`][fansi] for details on how _Control Sequences_ are #' interpreted, particularly if you are getting unexpected results, @@ -159,6 +164,8 @@ #' [`state_at_end`] to compute active state at the end of strings, #' [`close_state`] to compute the sequence required to close active state. #' @param x a character vector or object that can be coerced to such. +#' @param start integer. The first element to be extracted or replaced. +#' @param stop integer. The first element to be extracted or replaced. #' @param type character(1L) partial matching #' `c("chars", "width", "graphemes")`, although types other than "chars" only #' work correctly with R >= 3.2.2. See [`?nchar`][base::nchar]. diff --git a/man/fansi.Rd b/man/fansi.Rd index c5124b80..af202b02 100644 --- a/man/fansi.Rd +++ b/man/fansi.Rd @@ -3,6 +3,7 @@ \docType{package} \name{fansi} \alias{fansi} +\alias{fansi-package} \title{Details About Manipulation of Strings Containing Control Sequences} \description{ Counterparts to R string manipulation functions that account for @@ -122,13 +123,17 @@ window title or changing the active color palette. \href{https://iterm2.com/documentation-escape-codes.html}{Some terminals} have added support for associating URIs to text with OSCs in a similar way to anchors in HTML, so \code{fansi} interprets them and outputs or terminates them as -needed. For example:\preformatted{"\\033]8;;xy.z\\033\\\\LINK\\033]8;;\\033\\\\" -} +needed. For example: + +\if{html}{\out{
}}\preformatted{"\\033]8;;xy.z\\033\\\\LINK\\033]8;;\\033\\\\" +}\if{html}{\out{
}} Might be interpreted as link to the URI "x.z". To make the encoding pattern clearer, we replace "\033]" with "" and "\033\\\\" with -"" below:\preformatted{8;;URILINK TEXT8;; -} +"" below: + +\if{html}{\out{
}}\preformatted{8;;URILINK TEXT8;; +}\if{html}{\out{
}} } \section{State Interactions}{ @@ -182,7 +187,9 @@ new line with the currently active background before writing the contents of the line. If there is a non-default active background color, any unwritten columns in the new line will keep the prior background color even if the new line changes the background color. To avoid this be sure to use \code{terminate = TRUE} or to manually terminate each line with e.g. "ESC[0m". The -problem manifests as:\preformatted{" " = default background +problem manifests as: + +\if{html}{\out{
}}\preformatted{" " = default background "#" = new background ">" = start new background "!" = restore default background @@ -193,7 +200,7 @@ problem manifests as:\preformatted{" " = default background |!abc\\n#####| <- trailing "#" after newline are from pre-paint | abc | +-----------+ -} +}\if{html}{\out{
}} The simplest way to avoid this problem is to split input strings by any newlines they contain, and use \code{terminate = TRUE} (the default). A more diff --git a/man/strsplit_ctl.Rd b/man/strsplit_ctl.Rd index b7dac954..f75ad494 100644 --- a/man/strsplit_ctl.Rd +++ b/man/strsplit_ctl.Rd @@ -168,6 +168,14 @@ To maximize the odds of getting stable output set \code{normalize_state} to set \code{term.cap} to a specific set of capabilities. } +\section{Bidirectional Text}{ + + +\code{fansi} is unaware of text directionality and operates as if all strings are +left to right (LTR). Using \code{fansi} function with strings that contain mixed +direction scripts (i.e. both LTR and RTL) may produce undesirable results. +} + \examples{ strsplit_ctl("\033[31mhello\033[42m world!", " ") diff --git a/man/strtrim_ctl.Rd b/man/strtrim_ctl.Rd index 99764564..26734829 100644 --- a/man/strtrim_ctl.Rd +++ b/man/strtrim_ctl.Rd @@ -31,7 +31,7 @@ strtrim2_ctl( \item{x}{a character vector, or an object which can be coerced to a character vector by \code{\link[base]{as.character}}.} -\item{width}{Positive integer values: recycled to the length of \code{x}.} +\item{width}{positive integer values: recycled to the length of \code{x}.} \item{warn}{TRUE (default) or FALSE, whether to warn when potentially problematic \emph{Control Sequences} are encountered. These could cause the diff --git a/man/strtrim_sgr.Rd b/man/strtrim_sgr.Rd index feb84688..e2e1a9e2 100644 --- a/man/strtrim_sgr.Rd +++ b/man/strtrim_sgr.Rd @@ -29,7 +29,7 @@ strtrim2_sgr( \item{x}{a character vector, or an object which can be coerced to a character vector by \code{\link[base]{as.character}}.} -\item{width}{Positive integer values: recycled to the length of \code{x}.} +\item{width}{positive integer values: recycled to the length of \code{x}.} \item{warn}{TRUE (default) or FALSE, whether to warn when potentially problematic \emph{Control Sequences} are encountered. These could cause the diff --git a/man/strwrap_ctl.Rd b/man/strwrap_ctl.Rd index 4de8cd1e..89c06adc 100644 --- a/man/strwrap_ctl.Rd +++ b/man/strwrap_ctl.Rd @@ -55,7 +55,7 @@ strwrap2_ctl( \item{exdent}{a non-negative integer specifying the indentation of subsequent lines in paragraphs.} -\item{prefix}{a character string to be used as prefix for +\item{prefix, initial}{a character string to be used as prefix for each line except the first, for which \code{initial} is used.} \item{simplify}{a logical. If \code{TRUE}, the result is a single @@ -65,9 +65,6 @@ strwrap2_ctl( (Hence, the result in the former case is obtained by unlisting that of the latter.)} -\item{initial}{a character string to be used as prefix for - each line except the first, for which \code{initial} is used.} - \item{warn}{TRUE (default) or FALSE, whether to warn when potentially problematic \emph{Control Sequences} are encountered. These could cause the assumptions \code{fansi} makes about how strings are rendered on your display @@ -242,6 +239,14 @@ To maximize the odds of getting stable output set \code{normalize_state} to set \code{term.cap} to a specific set of capabilities. } +\section{Bidirectional Text}{ + + +\code{fansi} is unaware of text directionality and operates as if all strings are +left to right (LTR). Using \code{fansi} function with strings that contain mixed +direction scripts (i.e. both LTR and RTL) may produce undesirable results. +} + \examples{ hello.1 <- "hello \033[41mred\033[49m world" hello.2 <- "hello\t\033[41mred\033[49m\tworld" diff --git a/man/strwrap_sgr.Rd b/man/strwrap_sgr.Rd index 04c7aca0..5073be2b 100644 --- a/man/strwrap_sgr.Rd +++ b/man/strwrap_sgr.Rd @@ -53,7 +53,7 @@ strwrap2_sgr( \item{exdent}{a non-negative integer specifying the indentation of subsequent lines in paragraphs.} -\item{prefix}{a character string to be used as prefix for +\item{prefix, initial}{a character string to be used as prefix for each line except the first, for which \code{initial} is used.} \item{simplify}{a logical. If \code{TRUE}, the result is a single @@ -63,9 +63,6 @@ strwrap2_sgr( (Hence, the result in the former case is obtained by unlisting that of the latter.)} -\item{initial}{a character string to be used as prefix for - each line except the first, for which \code{initial} is used.} - \item{warn}{TRUE (default) or FALSE, whether to warn when potentially problematic \emph{Control Sequences} are encountered. These could cause the assumptions \code{fansi} makes about how strings are rendered on your display diff --git a/man/substr_ctl.Rd b/man/substr_ctl.Rd index 4384b780..777a65ef 100644 --- a/man/substr_ctl.Rd +++ b/man/substr_ctl.Rd @@ -68,7 +68,7 @@ substr2_ctl( \item{start}{integer. The first element to be extracted or replaced.} -\item{stop}{integer. The last element to be extracted or replaced.} +\item{stop}{integer. The first element to be extracted or replaced.} \item{warn}{TRUE (default) or FALSE, whether to warn when potentially problematic \emph{Control Sequences} are encountered. These could cause the @@ -192,15 +192,19 @@ OSC hyperlinks. See \code{\link{fansi}} for details. When computing substrings, \emph{Normal} (non-control) characters are considered to occupy positions in strings, whereas \emph{Control Sequences} occupy the -interstices between them. The string:\preformatted{"hello-\\033[31mworld\\033[m!" -} +interstices between them. The string: + +\if{html}{\out{
}}\preformatted{"hello-\\033[31mworld\\033[m!" +}\if{html}{\out{
}} -is interpreted as:\preformatted{ 1 1 1 +is interpreted as: + +\if{html}{\out{
}}\preformatted{ 1 1 1 1 2 3 4 5 6 7 8 9 0 1 2 h e l l o -|w o r l d|! ^ ^ \\033[31m \\033[m -} +}\if{html}{\out{
}} \code{start} and \code{stop} reference character positions so they never explicitly select for the interstitial \emph{Control Sequences}. The latter are implicitly @@ -308,6 +312,14 @@ The \href{https://cran.r-project.org/package=utf8}{\code{utf8}} package provides conforming grapheme parsing implementation. } +\section{Bidirectional Text}{ + + +\code{fansi} is unaware of text directionality and operates as if all strings are +left to right (LTR). Using \code{fansi} function with strings that contain mixed +direction scripts (i.e. both LTR and RTL) may produce undesirable results. +} + \examples{ substr_ctl("\033[42mhello\033[m world", 1, 9) substr_ctl("\033[42mhello\033[m world", 3, 9) diff --git a/man/substr_sgr.Rd b/man/substr_sgr.Rd index 470c7616..65196513 100644 --- a/man/substr_sgr.Rd +++ b/man/substr_sgr.Rd @@ -36,7 +36,7 @@ substr2_sgr( \item{start}{integer. The first element to be extracted or replaced.} -\item{stop}{integer. The last element to be extracted or replaced.} +\item{stop}{integer. The first element to be extracted or replaced.} \item{warn}{TRUE (default) or FALSE, whether to warn when potentially problematic \emph{Control Sequences} are encountered. These could cause the diff --git a/man/trimws_ctl.Rd b/man/trimws_ctl.Rd index e6ea86cb..0488c24c 100644 --- a/man/trimws_ctl.Rd +++ b/man/trimws_ctl.Rd @@ -15,7 +15,7 @@ trimws_ctl( ) } \arguments{ -\item{x}{a character vector} +\item{x}{a character vector.} \item{which}{a character string specifying whether to remove both leading and trailing whitespace (default), or only leading