File Coverage

blib/lib/UI/Various/PoorTerm/base.pm
Criterion Covered Total %
statement 41 41 100.0
branch 8 8 100.0
condition 10 10 100.0
subroutine 9 9 100.0
pod n/a
total 68 68 100.0


line stmt bran cond sub pod time code
1             package UI::Various::PoorTerm::base;
2              
3             # Author, Copyright and License: see end of file
4              
5             =head1 NAME
6              
7             UI::Various::PoorTerm::base - abstract helper class for PoorTerm's UI elements
8              
9             =head1 SYNOPSIS
10              
11             # This module should only be used by the UI::Various::PoorTerm UI
12             # element classes!
13              
14             =head1 ABSTRACT
15              
16             This module provides some helper functions for the UI elements of the
17             minimal fallback UI.
18              
19             =head1 DESCRIPTION
20              
21             The documentation of this module is only intended for developers of the
22             package itself.
23              
24             All functions of the module will be included as second "base
25             class" (in C<@ISA>). Note that this is not a diamond pattern as this "base
26             class" does not import anything besides C.
27              
28             =cut
29              
30             #########################################################################
31              
32 11     11   108 use v5.14;
  11         28  
33 11     11   50 use strictures;
  11         18  
  11         48  
34 11     11   1512 no indirect 'fatal';
  11         14  
  11         55  
35 11     11   566 no multidimensional;
  11         31  
  11         54  
36 11     11   315 use warnings 'once';
  11         18  
  11         423  
37              
38 11     11   4452 use Text::Wrap;
  11         25168  
  11         890  
39             $Text::Wrap::huge = 'overflow';
40             $Text::Wrap::unexpand = 0;
41              
42             our $VERSION = '0.24';
43              
44 11     11   71 use UI::Various::core;
  11         18  
  11         60  
45              
46             require Exporter;
47             our @ISA = qw(Exporter);
48             our @EXPORT_OK = qw();
49              
50             #########################################################################
51             #########################################################################
52              
53             =head1 METHODS
54              
55             The module provides the following common (internal) methods for all
56             UI::Various::PoorTerm UI element classes:
57              
58             =cut
59              
60             #########################################################################
61              
62             =head2 B<_cut> - cut string according to width of UI element
63              
64             $wrapped_string = $ui_element->_cut($string, ...);
65              
66             =head3 example:
67              
68             print $self->_cut($prefix, ' ', $self->text), "\n";
69              
70             =head3 parameters:
71              
72             $string the string(s) to be shortened
73              
74             =head3 description:
75              
76             This method joins all strings passed to it. It then checks if they fit
77             within the L and that
78             the length of the strings do not exceed the defined width for the UI element
79             itself. Any excess content is cut away.
80              
81             Note that method is unfit for multi-line strings. Also note that the
82             specific width of the UI element is transitive meaning that it could be
83             defined in one of the parents of the UI element itself.
84              
85             =head3 returns:
86              
87             the (maybe) shortened string
88              
89             =cut
90              
91             # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
92              
93             sub _cut($@)
94             {
95 196     196   297 my $self = shift;
96 196         358 my $string = join('', @_);
97              
98 196         231 my $len = length($string);
99 196   100     466 my $width = $self->width || 0;
100 196         404 my $max_width = $self->top->max_width;
101              
102 196 100       361 $width <= $max_width or $width = $max_width;
103 196 100 100     360 if ($len <= $width or $width < 1)
104             {
105 195         2604 return $string;
106             }
107 1         16 return substr($string, 0, $width);
108             }
109              
110             #########################################################################
111              
112             =head2 B<_wrap> - wrap string according to width of UI element
113              
114             $wrapped_string = $ui_element->_wrap($prefix, $string);
115              
116             =head3 example:
117              
118             print $self->_wrap($prefix, $self->text), "\n";
119              
120             =head3 parameters:
121              
122             $prefix text in front of first line
123             $string the string to be wrapped
124              
125             =head3 description:
126              
127             This method checks if the given prefix text and string fit within the
128             L, and that the length
129             of the string does not exceed the defined width for the UI element itself.
130              
131             If string plus prefix is longer than the maximum line length, or if the
132             string (without prefix!) is longer than the specific width for the UI
133             element, the string gets automatically wrapped at the last word boundary
134             before that length. Wrapped lines are prefixed with as much blanks as the
135             prefix of the first line has characters.
136              
137             Note that the specific width of the UI element is transitive meaning that it
138             could be defined in one of the parents of the UI element itself.
139              
140             Also note that if the method can't find a place to properly break up the
141             string, it gives up and returns a longer one.
142              
143             =head3 returns:
144              
145             the (hopefully correctly) wrapped string
146              
147             =cut
148              
149             # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
150              
151             sub _wrap($$$)
152             {
153 401     401   760 my ($self, $prefix, $string) = @_;
154              
155 401         549 my $len_p = length($prefix);
156 401         460 my $len_s = length($string);
157 401   100     930 my $width = $self->width || 0;
158 401         961 my $max_width = $self->top->max_width;
159              
160 401 100       833 $width <= $max_width - $len_p or $width = $max_width - $len_p;
161 401 100 100     856 if ($len_s <= $width or $width < 1)
162             {
163 394         6907 return $prefix.$string;
164             }
165 7         41 local $_ = ' ' x $len_p;
166 7         30 $Text::Wrap::columns = $width + $len_p + 1;
167 7         59 $_ = wrap($prefix, $_, $string);
168 7         1655 return $_;
169             }
170              
171             1;
172              
173             #########################################################################
174             #########################################################################
175              
176             =head1 SEE ALSO
177              
178             L
179              
180             =head1 LICENSE
181              
182             Copyright (C) Thomas Dorner.
183              
184             This library is free software; you can redistribute it and/or modify it
185             under the same terms as Perl itself. See LICENSE file for more details.
186              
187             =head1 AUTHOR
188              
189             Thomas Dorner Edorner (at) cpan (dot) orgE
190              
191             =cut