NAME

Text::WideChar::Util - Routines for text containing wide characters

VERSION

version 0.03

SYNOPSIS

use Text::WideChar::Util qw(
    mbpad mbswidth_height mbtrunc mbwrap wrap);

# get width as well as number of lines
say mbswidth_height("red\n红色"); # => [4, 2]

# wrap text to a certain column width
say mbwrap("....", 40);

# pad (left, right, center) text to specified column width, handle multilines
say mbpad("foo", 10);                          # => "foo       "
say mbpad("红色", 10, "left");                 # => "      红色"
say mbpad("foo\nbarbaz\n", 10, "center", "."); # => "...foo....\n..barbaz..\n"

# truncate text to a certain column width
say mbtrunc("红色", 2 ); # => "红"
say mbtrunc("红色", 3 ); # => "红"
say mbtrunc("红red", 3); # => "红r"

DESCRIPTION

This module provides routines for dealing with text containing wide characters (wide meaning occupying more than 1 column width in terminal).

FUNCTIONS

mbswidth_height($text) => [INT, INT]

Like Text::CharWidth's mbswidth(), but also gives height (number of lines). For example, mbswidth_height("foobar\nb\n") gives [6, 3].

mbwrap($text, $width, \%opts) => STR

Wrap $text to $width columns. It uses mbswidth() instead of Perl's length() which works on a per-character basis.

Options:

• tab_width => INT (default: 8)

  Set tab width.

  Note that tab will only have effect on the indent. Tab between text will be replaced with a single space.

• flindent => STR

  First line indent. If unspecified, will be deduced from the first line of text.

• slindent => STD

  Subsequent line indent. If unspecified, will be deduced from the second line of text, or if unavailable, will default to empty string ("").

Performance: ~2300/s on my Core i5-2400 3.1GHz desktop for a ~1KB of text.

wrap($text, $width, \%opts) => STR

Like mbwrap(), but uses character-based length() instead of column width-wise mbswidth(). Provided as an alternative to the venerable Text::Wrap's wrap() but with a different behaviour. This module's wrap() can reflow newline and its behavior is more akin to Emacs (try reflowing a paragraph in Emacs using M-q).

Performance: ~3100/s on my Core i5-2400 3.1GHz desktop for a ~1KB of text. Text::Wrap::wrap() on the other hand can go ~3800/s.

mbpad($text, $width[, $which[, $padchar[, $truncate]]]) => STR

Return $text padded with $padchar to $width columns. $which is either "r" or "right" for padding on the right (the default if not specified), "l" or "left" for padding on the right, or "c" or "center" or "centre" for left+right padding to center the text.

$padchar is whitespace if not specified. It should be string having the width of 1 column.

mbtrunc($text, $width) => STR

Truncate $text to $width columns. It uses mbswidth() instead of Perl's length(), so it can handle wide characters.

Does *not* handle multiple lines.

None are exported by default, but they are exportable.

FAQ

How do I truncate or pad to a certain character length (instead of column width)?

You can simply use Perl's substr() which works by character.

TODOS

SEE ALSO

Text::CharWidth which provides mbswidth().

Text::ANSI::Util which can also handle text containing wide characters as well ANSI escape codes.

AUTHOR

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Steven Haryanto.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Text::WideChar::Util

perl -MCPAN -e shell
install Text::WideChar::Util