File Coverage

blib/lib/Term/Size.pm
Criterion Covered Total %
statement 12 12 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 16 16 100.0


line stmt bran cond sub pod time code
1             package Term::Size;
2              
3 2     2   142027 use strict;
  2         13  
  2         69  
4 2     2   12 use vars qw(@EXPORT_OK @ISA $VERSION);
  2         4  
  2         114  
5              
6 2     2   11 use DynaLoader ();
  2         4  
  2         48  
7 2     2   11 use Exporter ();
  2         4  
  2         149  
8              
9             @ISA = qw(Exporter DynaLoader);
10             @EXPORT_OK = qw(chars pixels);
11              
12             $VERSION = '0.211';
13              
14             bootstrap Term::Size $VERSION;
15              
16             1;
17              
18             =encoding utf8
19              
20             =head1 NAME
21              
22             Term::Size - Retrieve terminal size on Unix
23              
24             =head1 SYNOPSIS
25              
26             use Term::Size;
27              
28             ($columns, $rows) = Term::Size::chars *STDOUT{IO};
29             ($x, $y) = Term::Size::pixels;
30              
31             =head1 DESCRIPTION
32              
33             L is a Perl module which provides a straightforward way to
34             retrieve the terminal size.
35              
36             Both functions take an optional filehandle argument, which defaults to
37             C<*STDIN{IO}>. They both return a list of two values, which are the
38             current width and height, respectively, of the terminal associated with
39             the specified filehandle.
40              
41             C returns the size in units of characters, whereas
42             C uses units of pixels.
43              
44             In a scalar context, both functions return the first element of the
45             list, that is, the terminal width.
46              
47             The functions may be imported.
48              
49             If you need to pass a filehandle to either of the L
50             functions, beware that the C<*STDOUT{IO}> syntax is only supported in
51             Perl 5.004 and later. If you have an earlier version of Perl, or are
52             interested in backwards compatibility, use C<*STDOUT> instead.
53              
54             =head1 EXAMPLES
55              
56             1. Refuse to run in a too narrow window.
57              
58             use Term::Size;
59              
60             die "Need 80 column screen" if Term::Size::chars *STDOUT{IO} < 80;
61              
62             2. Track window size changes.
63              
64             use Term::Size 'chars';
65              
66             my $changed = 1;
67              
68             while (1) {
69             local $SIG{'WINCH'} = sub { $changed = 1 };
70              
71             if ($changed) {
72             ($cols, $rows) = chars;
73             # Redraw, or whatever.
74             $changed = 0;
75             }
76             }
77              
78             =head1 RETURN VALUES
79              
80             If there is an error, both functions return C
81             in scalar context, or an empty list in list context.
82              
83             If the terminal size information is not available, the functions
84             will normally return C<(0, 0)>, but this depends on your system. On
85             character only terminals, C will normally return C<(0, 0)>.
86              
87             =head1 CAVEATS
88              
89             L only works on Unix systems, as it relies on the
90             C function to retrieve the terminal size. If you need
91             terminal size in Windows, see L.
92              
93             Before version 0.208, C and C used to return false on error.
94              
95             =head1 SEE ALSO
96              
97             L, L, L, L.
98              
99             =head1 AUTHOR
100              
101             Tim Goodwin, , 1997-04-23.
102              
103             =head1 MANTAINER
104              
105             Adriano Ferreira, , 2006-05-19.
106              
107             =head1 COPYRIGHT AND LICENSE
108              
109             Copyright (C) 1997-05-13 by Tim Goodwin.
110              
111             You may redistribute them under the same terms as Perl itself.
112              
113             =cut