File Coverage

blib/lib/Text/ANSI/Fold/Util.pm

Criterion	Covered	Total	%
statement	36	36	100.0
branch	4	4	100.0
condition	3	4	75.0
subroutine	15	15	100.0
pod	4	4	100.0
total	62	63	98.4

package Text::ANSI::Fold::Util;
our $VERSION = "0.06";

use v5.14;
use utf8;
use warnings;
use Data::Dumper;

use Exporter qw(import);
our @EXPORT_OK;
our %EXPORT_TAGS = ( all => [ @EXPORT_OK ] );

use List::Util qw(max);
use Text::ANSI::Fold qw(ansi_fold);

=encoding utf-8

=head1 NAME

Text::ANSI::Fold::Util - Text::ANSI::Fold utilities (width, substr)

=head1 SYNOPSIS

    use Text::ANSI::Fold::Util qw(:all);
    use Text::ANSI::Fold::Util qw(ansi_width ansi_substr);
    ansi_width($text);
    ansi_substr($text, $offset, $width [, $replacement]);

    use Text::ANSI::Fold::Util;
    Text::ANSI::Fold::Util::width($text);
    Text::ANSI::Fold::Util::substr($text, ...);

    # ansi_expand() was moved to Text::ANSI::Tabs
    ansi_expand($text);
    Text::ANSI::Fold::Util::expand($text);

=head1 VERSION

Version 0.06

=head1 DESCRIPTION

This is a collection of utilities using Text::ANSI::Fold module.  All
functions are aware of ANSI terminal sequence.

=head1 FUNCTION

There are exportable functions start with B prefix, and
unexportable functions without them.

=over 7

=cut


=item B(I)

=item B(I)

Returns visual width of given text.

=cut

BEGIN { push @EXPORT_OK, qw(&ansi_width) }
sub ansi_width { goto &width }

sub width {
    (ansi_fold($_[0], -1))[2];
}


=item B(I, I, I [, I])

=item B(I, I, I [, I])

Returns substring just like Perl's B function, but string
position is calculated by the visible width on the screen instead of
number of characters.

If an optional I parameter is given, replace the substring
by the replacement and return the entire string.

It does not cut the text in the middle of multi-byte character, of
course.  Its behavior depends on the implementation of lower module.

=cut

BEGIN { push @EXPORT_OK, qw(&ansi_substr) }
sub ansi_substr { goto &substr }

sub substr {
    my($text, $offset, $length, $replacement) = @_;
    if ($offset < 0) {
	$offset = max(0, $offset + ansi_width($text));
    }
    my @s = Text::ANSI::Fold
	->new(text => $text, width => [ $offset, $length // -1, -1 ])
	->chops;
    if (defined $replacement) {
	$s[0] . $replacement . ($s[2] // '');
    } else {
	$s[1];
    }
}


=item B(I, ...)

=item B(I, ...)

This function is now moved to L module.  Interface
remains only for backward compatibility, and may be deprecated in the
future.

=cut

use Text::ANSI::Tabs qw(ansi_expand);
BEGIN { push @EXPORT_OK, qw(&ansi_expand) }
*tabstop = \$Text::ANSI::Tabs::tabstop;
*expand  = \&Text::ANSI::Tabs::expand;

=back

=cut

1;

__END__