File Coverage

blib/lib/Term/Scroller.pm
Criterion Covered Total %
statement 135 138 97.8
branch 35 42 83.3
condition 26 40 65.0
subroutine 19 19 100.0
pod 3 3 100.0
total 218 242 90.0


line stmt bran cond sub pod time code
1             package Term::Scroller;
2              
3 5     5   444001 use 5.020;
  5         59  
4 5     5   29 use strict;
  5         7  
  5         102  
5 5     5   25 use warnings;
  5         10  
  5         136  
6              
7 5     5   37 use feature 'unicode_strings';
  5         11  
  5         823  
8              
9             our $VERSION = '1.2';
10              
11             =head1 NAME
12              
13             Term::Scroller - Display text in a scrolling viewport in your terminal
14              
15             =head1 SYNOPSIS
16              
17             use Term::Scroller;
18            
19             # Default options
20             my $scroll = Term::Scroller->new();
21             print $scroll "blah blah blah\n" for (1..100);
22             # You should always call the end() method when you're done
23             $scroll->end();
24              
25             # Some more options (limited window size, with a border)
26             $scroll = scroller(width => 40, height => 5, window => '-#-#-#-#');
27             print $scroll "beee daah booo\n" for (1..100);
28             $scroll->end();
29              
30             # See the rest of the documentation for more options!
31              
32             =head1 DESCRIPTION
33              
34             B provides you with a way to view a large stream of text
35             inside a small, scrolling viewport on your terminal. The size and borders of
36             the viewport/window can be customized along with a number of other control
37             options.
38              
39             For a command-line program that uses this to display the output of commands
40             see L.
41              
42             =cut
43              
44 5     5   603 use IO::Handle;
  5         6292  
  5         272  
45              
46 5     5   34 use Carp;
  5         10  
  5         315  
47 5     5   33 use Symbol qw(qualify_to_ref);
  5         10  
  5         233  
48 5     5   30 use Scalar::Util qw(openhandle);
  5         10  
  5         284  
49 5     5   35 use List::Util qw(any);
  5         10  
  5         567  
50              
51 5     5   2783 use IO::Pty;
  5         69619  
  5         265  
52 5     5   2740 use Term::ReadKey qw(GetTerminalSize);
  5         9911  
  5         332  
53              
54 5     5   2240 use Term::Scroller::Linefeed qw(linefeed);
  5         14  
  5         5981  
55              
56             our @ISA = qw(IO::Pty);
57              
58             =head1 Methods
59              
60             =head2 new
61              
62             Returns a new scroller instance. The scroller is a filehandle
63             (actually an instance of L) where anything written to
64             it is displayed in the scrolling window. The scroller will sanitize any
65             cursor-related ANSI escape sequences so text that expects them to work might
66             look garbled, but at least it should be very difficult to escape or break the
67             window. color-related ANSI sequences are left untouched though so colored
68             text will still work inside the window.
69              
70             I
71              
72             The arguments to B are interpreted as a hash and can contain the
73             following options:
74              
75             =head3 Size & Styling Options
76              
77             =over 4
78              
79             =item * B
80              
81             Integer representing the maximum height (in lines) of the viewport. The window
82             will grow as more lines of input come in and start scrolling once it reaches
83             this height. (B: 10)
84              
85             =item * B
86              
87             Integer representing the maximum width (in columns) of the viewport. Input lines
88             will truncated at this width, not including ANSI escape sequences.
89             (B: the width of the connected terminal, or 80 if the width
90             couldn't be determined for some reason).
91              
92             =item * B
93              
94             Integer representing the width of tabs (in characters) when viewed in the
95             viewport. For consistent printing, tabs are replaced with this number of
96             spaces. (B: 4)
97              
98             =item * B