File Coverage

blib/lib/Text/ANSI/Fold/Util.pm
Criterion Covered Total %
statement 33 34 97.0
branch 5 6 83.3
condition 4 4 100.0
subroutine 13 13 100.0
pod 4 4 100.0
total 59 61 96.7


line stmt bran cond sub pod time code
1             package Text::ANSI::Fold::Util;
2             our $VERSION = "1.05";
3              
4 3     3   702276 use v5.14;
  3         15  
5 3     3   1256 use utf8;
  3         677  
  3         43  
6 3     3   125 use warnings;
  3         8  
  3         194  
7 3     3   2291 use Data::Dumper;
  3         39865  
  3         365  
8              
9 3     3   39 use Exporter qw(import);
  3         6  
  3         296  
10             our @EXPORT_OK;
11             our %EXPORT_TAGS = ( all => [ @EXPORT_OK ] );
12              
13 3     3   24 use List::Util qw(max);
  3         7  
  3         255  
14 3     3   5828 use Text::ANSI::Fold qw(ansi_fold);
  3         196787  
  3         478  
15              
16             =encoding utf-8
17              
18             =head1 NAME
19              
20             Text::ANSI::Fold::Util - Text::ANSI::Fold utilities (width, substr)
21              
22             =head1 SYNOPSIS
23              
24             use Text::ANSI::Fold::Util qw(:all);
25             use Text::ANSI::Fold::Util qw(ansi_width ansi_substr);
26             ansi_width($text);
27             ansi_substr($text, $offset, $width [, $replacement]);
28              
29             use Text::ANSI::Fold::Util;
30             Text::ANSI::Fold::Util::width($text);
31             Text::ANSI::Fold::Util::substr($text, ...);
32              
33             =head1 VERSION
34              
35             Version 1.05
36              
37             =head1 DESCRIPTION
38              
39             This is a collection of utilities using Text::ANSI::Fold module. All
40             functions are aware of ANSI terminal sequence.
41              
42             =head1 FUNCTION
43              
44             There are exportable functions start with B prefix, and
45             unexportable functions without them.
46              
47             Unless otherwise noted, these functions are executed in the same
48             context as C exported by C module. That
49             is, the parameters set by C<< Text::ANSI::Fold->configure >> are
50             effective.
51              
52             =over 7
53              
54             =cut
55              
56              
57             =item B(I)
58              
59             =item B(I)
60              
61             Returns visual width of given text.
62              
63             =cut
64              
65 3     3   340 BEGIN { push @EXPORT_OK, qw(&ansi_width) }
66 6     6 1 221018 sub ansi_width { goto &width }
67              
68             sub width {
69 6     6 1 38 (ansi_fold($_[0], -1))[2];
70             }
71              
72              
73             =item B(I, I, I [, I])
74              
75             =item B(I, I, I [, I])
76              
77             Returns substring just like Perl's B function, but string
78             position is calculated by the visible width on the screen instead of
79             number of characters. If there is no corresponding substring, undef
80             is returned always.
81              
82             If the C option is specified, then if there is a
83             corresponding substring, it is padded to the specified width and
84             returned.
85              
86             It does not cut the text in the middle of multi-byte character. If
87             you want to split the text in the middle of a wide character, specify
88             the C option.
89              
90             Text::ANSI::Fold->configure(splitwide => 1);
91              
92             If an optional I parameter is given, replace the
93             substring by the replacement and return the entire string. If 0 is
94             specified for the width, there may be no error even if the
95             corresponding substring does not exist.
96              
97             =cut
98              
99 3     3   694 BEGIN { push @EXPORT_OK, qw(&ansi_substr) }
100 2     2 1 314209 sub ansi_substr { goto &substr }
101              
102             sub substr {
103 18     18 1 20212 my($text, $offset, $length, $replacement) = @_;
104 18 100       60 if ($offset < 0) {
105 4         15 $offset = max(0, $offset + ansi_width($text));
106             }
107 18   100     1166 my @s = (state $fold = Text::ANSI::Fold->configure)
108             ->text($text)
109             ->chops(width => [ $offset, $length // -1, -1 ]);
110 18 100       30344 if (defined $replacement) {
111 4 50       11 if (defined $s[1]) {
112 4   100     28 $s[0] . $replacement . ($s[2] // '');
113             } else {
114 0         0 undef;
115             }
116             } else {
117 14         58 $s[1];
118             }
119             }
120              
121              
122             =back
123              
124             =cut
125              
126             1;
127              
128             __END__