README
1NAME
2 Text::ANSI::WideUtil - Routines for text containing ANSI color codes
3 (wide-character functions only)
4
5VERSION
6 This document describes version 0.232 of Text::ANSI::WideUtil (from Perl
7 distribution Text-ANSI-WideUtil), released on 2021-04-14.
8
9SYNOPSIS
10 use Text::ANSI::WideUtil qw(
11 ta_mbpad
12 ta_mbsubstr
13 ta_mbswidth
14 ta_mbswidth_height
15 ta_mbtrunc
16 ta_mbwrap
17 );
18
19 # calculate visual width of text if printed on terminal (can handle Unicode
20 # wide characters and exclude the ANSI color codes)
21 say ta_mbswidth("\e[31mred"); # => 3
22 say ta_mbswidth("\e[31m红色"); # => 4
23
24 # ditto, but also return the number of lines
25 say ta_mbswidth_height("\e[31mred\n红色"); # => [4, 2]
26
27 # wrap text to a certain column width, handle ANSI color codes
28 say ta_mbwrap(...);
29
30 # pad (left, right, center) text to a certain width
31 say ta_mbpad(...);
32
33 # truncate text to a certain width while still passing ANSI color codes
34 say ta_mbtrunc(...);
35
36 # get substring, like ta_substr()
37 my $substr = ta_mbsubstr("...", $pos, $len);
38
39 # return text but with substring replaced with replacement
40 say ta_mbsubstr("...", $pos, $len, $replacement);
41
42DESCRIPTION
43 This module contains the wide-character variant ("ta_mb*()") for some
44 functions in Text::ANSI::Util. It is split so only this module requires
45 Text::WideChar::Util and Text::ANSI::Util can be kept slim.
46
47FUNCTIONS
48 ta_mbpad($text, $width[, $which[, $padchar[, $truncate]]]) => STR
49 Pad <$text> to $width. Like "ta_pad()" but it uses "ta_mbswidth()" to
50 determine visual width instead of "ta_length()". See documentation for
51 "ta_pad()" for more details on the other arguments.
52
53 ta_mbtrunc($text, $width) => STR
54 Truncate $text to $width. Like "ta_trunc()" but it uses "ta_mbswidth()"
55 to determine visual width instead of "ta_length()".
56
57 ta_mbswidth($text) => INT
58 Return visual width of $text (in number of columns) if printed on
59 terminal. Equivalent to
60 "Text::WideChar::Util::mbswidth(ta_strip($text))". This function can be
61 used e.g. in making sure that your text aligns vertically when output to
62 the terminal in tabular/table format.
63
64 Note that "ta_mbswidth()" handles multiline text correctly, e.g.:
65 "ta_mbswidth("foo\nbarbaz")" gives 6 instead of 3-1+8 = 8. It splits the
66 input text first with "/\r?\n/" as separator.
67
68 ta_mbswidth_height($text) => [INT, INT]
69 Like "ta_mbswidth()", but also gives height (number of lines). For
70 example, "ta_mbswidth_height("西爪哇\nb\n")" gives "[6, 3]".
71
72 ta_mbwrap($text, $width, \%opts) => STR
73 Like "ta_wrap()", but it uses "ta_mbswidth()" to determine visual width
74 instead of "ta_length()".
75
76 Performance: ~300/s on my Core i5 1.7GHz laptop for a ~1KB of text (with
77 zero to moderate amount of color codes). As a comparison,
78 Text::WideChar::Util's mbwrap() can do about 650/s.
79
80 ta_mbsubstr($text, $pos, $len[ , $replacement ]) => STR
81 Like "ta_substr()", but handles wide characters. $pos is counted in
82 visual width, not number of characters.
83
84FAQ
85 Why split functionalities of wide character and color support into multiple modules/distributions?
86 Performance (see numbers in the function description), dependency
87 (Unicode::GCString is used for wide character support), and overhead
88 (loading Unicode::GCString).
89
90 How do I truncate string based on number of characters instead of columns?
91 You can simply use "ta_trunc()" even on text containing wide characters.
92 ta_trunc() uses Perl's length() which works on a per-character basis.
93
94HOMEPAGE
95 Please visit the project's homepage at
96 <https://metacpan.org/release/Text-ANSI-WideUtil>.
97
98SOURCE
99 Source repository is at
100 <https://github.com/perlancar/perl-Text-ANSI-WideUtil>.
101
102BUGS
103 Please report any bugs or feature requests on the bugtracker website
104 <https://github.com/perlancar/perl-Text-ANSI-WideUtil/issues>
105
106 When submitting a bug or request, please include a test-file or a patch
107 to an existing test-file that illustrates the bug or desired feature.
108
109SEE ALSO
110 Text::ANSI::Util, Text::WideChar::Util, Text::NonWideChar::Util,
111 Text::Wrap, String::Pad
112
113 <http://en.wikipedia.org/wiki/ANSI_escape_code>
114
115 CLI's that use functions from this module include: dux from App::dux
116 ("dux wrap", "dux lpad", "dux rpad").
117
118AUTHOR
119 perlancar <perlancar@cpan.org>
120
121COPYRIGHT AND LICENSE
122 This software is copyright (c) 2021, 2020, 2015 by perlancar@cpan.org.
123
124 This is free software; you can redistribute it and/or modify it under
125 the same terms as the Perl 5 programming language system itself.
126
127