-Wformat warnings.fansi-package now that it is no longer
auto-generated by roxgen2 from the @docType package directive.@inheritParams.CRAN compiled code warning suppression release.
sprintf to snprintf.This is a major release and includes some behavior changes.
substr_cl (i.e substr_ctl<-).state_at_end to compute active state at end of a string.close_state to generate a closing sequence given an active state.trimws_ctl as an
equivalent to trimws.normalize_sgr converts
compound Control Sequences into normalized form (e.g. "ESC[44;31m"
becomes "ESC[31mESC[44m") for better compatibility with
crayon. Additionally, most functions
gain a normalize parameter so that they may return their output in
normalized form (h/t @krlmlr).substr_ctl and related
functions are now all-C instead of a combination of C offset computations and
R level substr operations. This greatly improves performance, particularly
for vectors with many distinct strings. Despite documentation claiming
otherwise, substr_ctl was quite slow in that case.type="width" mode, as well as a
type="graphemes" mode to measure in graphemes instead of characters.
Implementation is based on heuristics designed to work in most common use
cases.html_esc gains a what parameter to indicate which HTML special characters
should be escaped.carry and terminate parameters to control how fansi
generated substrings interact with surrounding formats.getOption now always have explicit fallback values defined
(h/t @gadenbui).unhandled_ctl for adjacent Control Sequences.term.cap parameter now accepts "all" as value, like the ctl parameter.substr_sgr, strwrap_sgr) are deprecated.
They will likely live on indefinitely, but they are of limited usefulness and
with the added support for OSC hyperlinks their name is misleading.sgr_to_html is now to_html with slight modifications to semantics; the old
function remains and does not warn about unescaped "<" or ">" in the
input string.The major intentional behavior change is to default fansi to always recognize
true color CSI SGR sequences (e.g. "ESC[38;2;128;50;245m"). The prior
default was to match the active terminal capabilities, but it is unlikely that
the intent of a user manipulating a string with truecolor sequences is to
interpret them incorrectly, even if their terminal does. fansi will continue
to warn in this case. To keep the pre-1.0 behavior add "old" to the
term.cap parameter.
Additionally, to_html will now warn if it encounters unescaped HTML special
character "<" or ">" in the input string.
Finally, the 1.0 release is an extensive refactoring of many parts of the
SGR and OSC hyperlink controls (Special Sequences) intake and output
algorithms. In some cases this means that some fansi functions will output
Special Sequences slightly differently than they did before. In almost all
cases the rendering of the output should remain unchanged, although there are
some corner cases with changes (e.g. in strwrap_ctl SGRs embedded in
whitespace sequences don't break the sequence).
The changes are a side effect of applying more consistent treatment of corner
cases around leading and trailing control sequences and (partially) invalid
control sequences. Trailing Special Sequences in the output is now omitted as
it would be immediately closed (assuming terminate=TRUE, the default).
Leading SGR is interpreted and re-output.
Normally output consistency alone would not be a reason to change behavior, but in this case the changes should be almost always undetectable in the rendered output, and maintaining old inconsistent behavior in the midst of a complete refactoring of the internals was beyond my patience. I apologize if these behavior changes adversely affect your programs.
WARNING: we will strive to keep rendered appearance of
fansioutputs consistent across releases, but the exact bytes used in the output of Special Sequences may change.
Other changes:
strip_ctl only warns with malformed CSI and OSC if they are reported as
supported via the ctl parameter. If CSI and OSC are indicated as not
supported, but two byte escapes are, the two initial bytes of CSI and OSCs
will be stripped.nchar_ctl preserves dim, dimnames, and names as the base functions do.tabs_as_spaces to handle sequential tabs, and to perform better on very
wide strings.nchar_ctl(...) is no longer a wrapper for nchar(strip_ctl(...)) so that it
may correctly support grapheme width calculations.sgr_to_html optionally
converts CSI SGR to classes instead of inline styles (h/t @hadley).sgr_to_html is more
disciplined about emitting unnecessary HTML (h/t @hadley).sgr_256: Display all 256 8-bit colors.in_html: Easily output HTML in a web page.make_styles: Easily produce CSS that matches 8-bit colors.nchar(..., type='width') for C0-C1 control characters
in R 4.1.split.nl option
to set_knit_hooks to mitigate white space issues when using blackfriday for
the markdown->html conversion (@krlmlr).ctl
parameter to most functions. Some functions such as strip_ctl had existing
parameters that did the same thing (e.g. strip, or which), and those have
been deprecated in favor of ctl. While technically this is a change in the
API, it is backwards compatible (addresses
#56 among and other things).*_sgr version of most *_ctl functions.nzchar_ctl gains the ctl parameter.strsplit_ctl can now work
with ctl parameters containing escape sequences provided those sequences
are excluded from by the ctl parameter.sgr_to_html so that
it can handle vector elements with un-terminated SGR sequences (@krlmlr).strwrap_ctl when
indent/exdent/prefix/initial widths vary from first to second line.strwrap2_*(..., strip.spaces=FALSE), including a bug when
wrap.always=TRUE and a line started in a word-whitespace boundary.term.cap parameter to unhandled_ctl.fansi::set_knit_hooks makes it easy to automatically convert ANSI CSI SGR
sequences to HTML in Rmarkdown documents. We also add a vignette that
demonstrates how to do this.strsplit.substr behavior starting with
R-3.6.strsplit_ctl.Initial release.