File Coverage

blib/lib/Term/Size/Perl.pm

Criterion	Covered	Total	%
statement	3	16	18.7
branch	0	12	0.0
condition	0	3	0.0
subroutine	1	4	25.0
pod	2	2	100.0
total	6	37	16.2

package Term::Size::Perl;

use strict;

require Exporter;

our @ISA = qw(Exporter);
our @EXPORT_OK = qw(chars pixels);

our $VERSION = 0.029;

=head1 NAME

Term::Size::Perl - Perl extension for retrieving terminal size (Perl version)

=head1 SYNOPSIS

    use Term::Size::Perl;

    ($columns, $rows) = Term::Size::Perl::chars *STDOUT{IO};
    ($x, $y) = Term::Size::Perl::pixels;

=head1 DESCRIPTION

Yet another implementation of C. Now
in pure Perl, with the exception of a C probe run
on build time.

=head2 FUNCTIONS

=over 4

=item B

    ($columns, $rows) = chars($h);
    $columns = chars($h);

C returns the terminal size in units of characters
corresponding to the given filehandle C<$h>.
If the argument is ommitted, C<*STDIN{IO}> is used.
In scalar context, it returns the terminal width.

=item B

    ($x, $y) = pixels($h);
    $x = pixels($h);

C returns the terminal size in units of pixels
corresponding to the given filehandle C<$h>.
If the argument is ommitted, C<*STDIN{IO}> is used.
In scalar context, it returns the terminal width.

Many systems with character-only terminals will return C<(0, 0)>.

=back

=head1 SEE ALSO

It all began with L by Tim Goodwin. You may want to
have a look at:

    Term::Size
    Term::Size::Unix
    Term::Size::Win32
    Term::Size::ReadKey

It would be helpful if you send me the F generated by
the probe at build time.
Please reports bugs via CPAN RT,
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Term-Size-Perl

=head1 BUGS

I am having some hard time to make tests run correctly
under the C script. Some Unix systems do not seem to provide a
working tty inside automatic installers. I think it needs
some skip tests, but I am yet not sure what should be the
portable tests for this.

Update:
This distribution uses new tests to skip if filehandle
is not a tty. It was noticed that C and
C, for instance, provide a non-tty STDOUT
to the test script and automatic installers
could provide a non-tty STDIN. So the former tests
were basically wrong. I am improving my understanding
of the involved issues and I hope to soon fix the
tests for all of Term::Size modules.

=head1 AUTHOR

A. R. Ferreira, [e-mail]

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2006-2007 by A. R. Ferreira

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut

require Term::Size::Perl::Params;
my %params = Term::Size::Perl::Params::params();

# ( row, col, x, y )
sub _winsize {
    my $h = shift || *STDIN;
    return unless -t $h;
    my $sz = "\0" x $params{winsize}{sizeof};
    ioctl($h, $params{TIOCGWINSZ}{value}, $sz)
        or return;
    return unpack $params{winsize}{mask}, $sz;
}

sub chars {
    my @sz = _winsize(shift);
    return unless @sz;
    return @sz[1, 0] if wantarray;
    return $sz[1];
}

sub pixels {
    my @sz = _winsize(shift);
    return unless @sz;
    return @sz[2, 3] if wantarray;
    return $sz[2];
}

1;