NAME
Text::ANSI::WideUtil - Routines for text containing ANSI color codes (wide-character functions only)
VERSION
This document describes version 0.232 of Text::ANSI::WideUtil (from Perl distribution Text-ANSI-WideUtil), released on 2021-04-14.
SYNOPSIS
use Text::ANSI::WideUtil qw(
ta_mbpad
ta_mbsubstr
ta_mbswidth
ta_mbswidth_height
ta_mbtrunc
ta_mbwrap
);
# calculate visual width of text if printed on terminal (can handle Unicode
# wide characters and exclude the ANSI color codes)
say ta_mbswidth("\e[31mred"); # => 3
say ta_mbswidth("\e[31m红色"); # => 4
# ditto, but also return the number of lines
say ta_mbswidth_height("\e[31mred\n红色"); # => [4, 2]
# wrap text to a certain column width, handle ANSI color codes
say ta_mbwrap(...);
# pad (left, right, center) text to a certain width
say ta_mbpad(...);
# truncate text to a certain width while still passing ANSI color codes
say ta_mbtrunc(...);
# get substring, like ta_substr()
my $substr = ta_mbsubstr("...", $pos, $len);
# return text but with substring replaced with replacement
say ta_mbsubstr("...", $pos, $len, $replacement);DESCRIPTION
This module contains the wide-character variant (ta_mb*()) for some functions in Text::ANSI::Util. It is split so only this module requires Text::WideChar::Util and Text::ANSI::Util can be kept slim.
FUNCTIONS
ta_mbpad($text, $width[, $which[, $padchar[, $truncate]]]) => STR
Pad <$text> to $width. Like ta_pad() but it uses ta_mbswidth() to determine visual width instead of ta_length(). See documentation for ta_pad() for more details on the other arguments.
ta_mbtrunc($text, $width) => STR
Truncate $text to $width. Like ta_trunc() but it uses ta_mbswidth() to determine visual width instead of ta_length().
ta_mbswidth($text) => INT
Return visual width of $text (in number of columns) if printed on terminal. Equivalent to Text::WideChar::Util::mbswidth(ta_strip($text)). This function can be used e.g. in making sure that your text aligns vertically when output to the terminal in tabular/table format.
Note that ta_mbswidth() handles multiline text correctly, e.g.: ta_mbswidth("foo\nbarbaz") gives 6 instead of 3-1+8 = 8. It splits the input text first with /\r?\n/ as separator.
ta_mbswidth_height($text) => [INT, INT]
Like ta_mbswidth(), but also gives height (number of lines). For example, ta_mbswidth_height("西爪哇\nb\n") gives [6, 3].
ta_mbwrap($text, $width, \%opts) => STR
Like ta_wrap(), but it uses ta_mbswidth() to determine visual width instead of ta_length().
Performance: ~300/s on my Core i5 1.7GHz laptop for a ~1KB of text (with zero to moderate amount of color codes). As a comparison, Text::WideChar::Util's mbwrap() can do about 650/s.
ta_mbsubstr($text, $pos, $len[ , $replacement ]) => STR
Like ta_substr(), but handles wide characters. $pos is counted in visual width, not number of characters.
FAQ
Why split functionalities of wide character and color support into multiple modules/distributions?
Performance (see numbers in the function description), dependency (Unicode::GCString is used for wide character support), and overhead (loading Unicode::GCString).
How do I truncate string based on number of characters instead of columns?
You can simply use ta_trunc() even on text containing wide characters. ta_trunc() uses Perl's length() which works on a per-character basis.
HOMEPAGE
Please visit the project's homepage at https://metacpan.org/release/Text-ANSI-WideUtil.
SOURCE
Source repository is at https://github.com/perlancar/perl-Text-ANSI-WideUtil.
BUGS
Please report any bugs or feature requests on the bugtracker website https://github.com/perlancar/perl-Text-ANSI-WideUtil/issues
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
SEE ALSO
Text::ANSI::Util, Text::WideChar::Util, Text::NonWideChar::Util, Text::Wrap, String::Pad
http://en.wikipedia.org/wiki/ANSI_escape_code
CLI's that use functions from this module include: dux from App::dux (dux wrap, dux lpad, dux rpad).
AUTHOR
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2021, 2020, 2015 by perlancar@cpan.org.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.