1NAME
2 Text::WideChar::Util - Routines for text containing wide characters
3
4VERSION
5 This document describes version 0.172 of Text::WideChar::Util (from Perl
6 distribution Text-WideChar-Util), released on 2021-04-14.
7
8SYNOPSIS
9 use Text::WideChar::Util qw(
10 mbpad pad mbswidth mbswidth_height mbtrunc trunc mbwrap wrap);
11
12 # get width as well as number of lines
13 say mbswidth_height("red\n红色"); # => [4, 2]
14
15 # wrap text to a certain column width
16 say mbwrap("....", 40);
17
18 # pad (left, right, center) text to specified column width, handle multilines
19 say mbpad("foo", 10); # => "foo "
20 say mbpad("红色", 10, "left"); # => " 红色"
21 say mbpad("foo\nbarbaz\n", 10, "center", "."); # => "...foo....\n..barbaz..\n"
22
23 # truncate text to a certain column width
24 say mbtrunc("红色", 2); # => "红"
25 say mbtrunc("红色", 3); # => "红"
26 say mbtrunc("红red", 3); # => "红r"
27
28DESCRIPTION
29 This module provides routines for dealing with text containing wide
30 characters (wide meaning occupying more than 1 column width in
31 terminal).
32
33INTERNAL NOTES
34 Should we wrap at hyphens? Probably not. Both Emacs as well as
35 Text::Wrap do not.
36
37FUNCTIONS
38 mbswidth($text) => INT
39 Like Text::CharWidth's mbswidth(), except implemented using
40 Unicode::GCString->new($text)->columns.
41
42 mbswidth_height($text) => [INT, INT]
43 Like mbswidth(), but also gives height (number of lines). For example,
44 "mbswidth_height("foobar\nb\n")" gives [6, 3].
45
46 length_height($text) => [INT, INT]
47 This is the non-wide version of mbswidth_height() and can be used if
48 your text only contains printable ASCII characters and newlines.
49
50 mbwrap($text, $width, \%opts) => STR
51 Wrap $text to $width columns. Replaces multiple whitespaces with a
52 single space.
53
54 It uses mbswidth() instead of Perl's length() which works on a
55 per-character basis. Has some support for wrapping Kanji/CJK
56 (Chinese/Japanese/Korean) text which do not have whitespace between
57 words.
58
59 Options:
60
61 * tab_width => INT (default: 8)
62
63 Set tab width.
64
65 Note that tab will only have effect on the indent. Tab between text
66 will be replaced with a single space.
67
68 * flindent => STR
69
70 First line indent. If unspecified, will be deduced from the first
71 line of text.
72
73 * slindent => STD
74
75 Subsequent line indent. If unspecified, will be deduced from the
76 second line of text, or if unavailable, will default to empty string
77 ("").
78
79 * return_stats => BOOL (default: 0)
80
81 If set to true, then instead of returning the wrapped string,
82 function will return "[$wrapped, $stats]" where $stats is a hash
83 containing some information like "max_word_width", "min_word_width".
84
85 * keep_trailing_space => BOOL (default: 0)
86
87 If set to true, then trailing space that separates words will be
88 kept at the end of wrapped lines. This option is useful if you want
89 to rejoin the lines later. Without this option set to true, wrapping
90 this line at width=4 (quotes shown):
91
92 "some long line"
93
94 will result in:
95
96 "some"
97 "long"
98 "line"
99
100 While if this option is set to true, the result will be:
101
102 "some "
103 "long "
104 "line"
105
106 Performance: ~450/s on my Core i5 1.7GHz laptop for a 1KB of text.
107
108 wrap($text, $width, \%opts) => STR
109 Like mbwrap(), but uses character-based length() instead of column
110 width-wise mbswidth(). Provided as an alternative to the venerable
111 Text::Wrap's wrap() but with a different behaviour. This module's wrap()
112 can reflow newline and its behavior is more akin to Emacs (try reflowing
113 a paragraph in Emacs using "M-q").
114
115 Performance: ~2000/s on my Core i5 1.7GHz laptop for a ~1KB of text.
116 Text::Wrap::wrap() on the other hand is ~2500/s.
117
118 mbpad($text, $width[, $which[, $padchar[, $truncate]]]) => STR
119 Return $text padded with $padchar to $width columns. $which is either
120 "r" or "right" for padding on the right (the default if not specified),
121 "l" or "left" for padding on the right, or "c" or "center" or "centre"
122 for left+right padding to center the text.
123
124 $padchar is whitespace if not specified. It should be string having the
125 width of 1 column.
126
127 pad($text, $width[, $which[, $padchar[, $truncate]]]) => STR
128 The non-wide version of mbpad(), just like in mbwrap() vs wrap().
129
130 mbtrunc($text, $width) => STR
131 Truncate $text to $width columns. It uses mbswidth() instead of Perl's
132 length(), so it can handle wide characters.
133
134 Does *not* handle multiple lines.
135
136 trunc($text, $width) => STR
137 The non-wide version of mbtrunc(), just like in mbwrap() vs wrap(). This
138 is actually not much more than Perl's "substr($text, 0, $width)".
139
140FAQ
141 Why split functionalities of wide character and color support into multiple modules/distributions?
142 Performance (see numbers in the function description), dependency
143 (Unicode::GCString is used for wide character support), and overhead
144 (loading Unicode::GCString).
145
146HOMEPAGE
147 Please visit the project's homepage at
148 <https://metacpan.org/release/Text-WideChar-Util>.
149
150SOURCE
151 Source repository is at
152 <https://github.com/perlancar/perl-Text-WideChar-Util>.
153
154BUGS
155 Please report any bugs or feature requests on the bugtracker website
156 <https://github.com/perlancar/perl-Text-WideChar-Util/issues>
157
158 When submitting a bug or request, please include a test-file or a patch
159 to an existing test-file that illustrates the bug or desired feature.
160
161SEE ALSO
162 Unicode::GCString which is consulted for visual width of characters.
163 Text::CharWidth is about 2.5x faster but it gives weird results (-1 for
164 characters like "\n" and "\t") and my Strawberry Perl installation fails
165 to build it.
166
167 Text::ANSI::Util which can also handle text containing wide characters
168 as well ANSI escape codes.
169
170 Text::WrapI18N which provides an alternative to wrap()/mbwrap() with
171 comparable speed, though wrapping result might differ slightly. And the
172 module currently uses Text::CharWidth.
173
174 Text::NonWideChar::Util contains non-wide version of some of the
175 abovementioned routines (the non-wide version of the routines will
176 eventually be moved here).
177
178 String::Pad, Text::Wrap
179
180AUTHOR
181 perlancar <perlancar@cpan.org>
182
183COPYRIGHT AND LICENSE
184 This software is copyright (c) 2021, 2019, 2015, 2014, 2013 by
185 perlancar@cpan.org.
186
187 This is free software; you can redistribute it and/or modify it under
188 the same terms as the Perl 5 programming language system itself.
189
190