James E Keenan > IO-Capture-Extended-0.11 > IO::Capture::Extended

Download:
IO-Capture-Extended-0.11.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.11   Source  

NAME ^

IO::Capture::Extended - Extend functionality of IO::Capture

VERSION ^

0.11, released September 6, 2006.

SYNOPSIS ^

The programmer interface consists of two classes:

IO::Capture::Stdout::Extended

    use IO::Capture::Stdout::Extended;

    $capture = IO::Capture::Stdout::Extended->new();
    $capture->start();
    # some code that prints to STDOUT
    $capture->stop();

    # scalar context:  return number of print statements with 'fox'
    $matches = $capture->grep_print_statements('fox');

    # list context:  return list of print statements with 'fox'
    @matches = $capture->grep_print_statements('fox');

    # return number of print statements
    $matches = $capture->statements;

    # scalar context:  return number of pattern matches
    $regex = qr/some regular expression/;
    $matches = $capture->matches($regex);

    # list context:  return list of pattern matches
    @matches = $capture->matches($regex);

    # return reference to array holding list of pattern matches
    $matchesref = $capture->matches_ref($regex);

    # scalar context:  return number of 'screen' lines printed
    $screen_lines = $capture->all_screen_lines();

    # list context:  return list of 'screen' lines printed
    @all_screen_lines = $capture->all_screen_lines();

IO::Capture::Stderr::Extended

    $capture = IO::Capture::Stderr::Extended->new();
    $capture->start();
    # some code that prints to STDERR
    $capture->stop();

... and then use all the methods defined above for IO::Capture::Stdout::Extended.

DESCRIPTION ^

IO::Capture::Extended is a distribution consisting of two classes, each of which is a collection of subroutines which are useful in extending the functionality of CPAN modules IO::Capture::Stdout and IO::Capture::Stderr, particularly when used in a testing context such as that provided by Test::Simple, Test::More or other modules built on Test::Builder.

USAGE ^

Requirements

IO::Capture distribution, available from CPAN http://search.cpan.org/~reynolds/IO-Capture-0.05/. Use version 0.05 or later to take advantage of important bug fixes. The IO::Capture distribution includes base class IO::Capture, IO::Capture::Stdout, IO::Capture::Stderr and other packages. It also includes useful documentation in IO::Capture::Overview.

General Comments

The IO::Capture::Stdout::Extended and IO::Capture::Stdout::Extended methods are designed to provide return values which work nicely as arguments to Test::More functions such as ok(), is() and like(). The examples below illustrate that objective. Suggestions are welcome for additional methods which would fulfill that objective.

Individual Methods

Note: Since IO::Capture::Extended is structured so as to make exactly the same methods available for IO::Capture::Stdout::Extended and IO::Capture::Stderr::Extended, whenver there appears below a reference to, e.g., IO::Capture::Stdout::Extended::grep_print_statements(), you should assume that the remarks apply equally to IO::Capture::Stderr::Extended::grep_print_statements(). Wherever reference is made to STDOUT, the remarks apply to STDERR as well.

grep_print_statements()

statements()

Problem: You've written a function which prints to STDOUT. You can make a prediction as to the number of screen lines which should be printed. You want to test that prediction with Test::More::is().

    sub print_greek {
        local $_;
        print "$_\n" for (qw| alpha beta gamma delta |);
    }

    $capture->start();
    print_greek();
    $capture->stop();
    is($capture->statements, 4, 
        "number of print statements is correct");

Solution: Precede the function call with a call to the IO::Capture::Stdout start() method and follow it with a call to the stop() method. Call IO::Capture::Stdout::Extended::statements() and use its return value as the first argument to is(). Use your prediction as the second argument to is(). Be sure to write a useful comment for your test.

Potential Pitfall: The number of print statements returned by statements is not necessarily the number of lines that would appear to be printed to standard output by a given block of code. If your subroutine or other code block prints partial lines -- i.e., lines lacking \n newline characters -- the number of print statements will be greater than the number of ''screen lines.'' This is illustrated by the following:

    sub print_greek_long {
        local $_;
        for (qw| alpha beta gamma delta |) {
            print $_;
            print "\n";
        }
    }

    $capture->start();
    print_greek_long();
    $capture->stop();
    is($capture->statements, 8, 
        "number of print statements is correct");

This pitfall can be avoided by using all_screen_lines() below.

all_screen_lines()

matches()

matches_ref()

Problem: Same as the first ''List Context'' example above, but now you would prefer to work with a method that returns an array reference rather than all the elements in a list.

    $matchesref = $capture->matches_ref($regex);
    is(${$matchesref}[0], $predicted, "first form matches test portion");

Solution: Call IO::Capture::Stdout::Extended::matches_ref() instead of matches. You will have to rephrase your test in terms of an element of a dereferenced array.

BUGS ^

As Paul Johnson says, ''Did I mention that this is alpha code?''.

SUPPORT ^

Contact the author or post to the perl-qa mailing list.

ACKNOWLEDGEMENTS ^

Thanks go first and foremost to the two authors of the IO::Capture distribution, Mark Reynolds and Jon Morgan. Mark Reynolds was responsive to this module's author's suggestions for bug fixes and additional tests. The documentation found in IO::Capture::Overview was particularly helpful in showing me how to extend IO::Capture's functionality. This distribution is maintained independently but will be updated as needed if and when IO::Capture is revised.

The methods in IO::Capture::Extended are offered to the Perl community in gratitude for being turned on to IO::Capture by David Cantrell on the perl.qa mailing list in February 2005 (http://www.nntp.perl.org/group/perl.qa/3567).

Other contributors to that discussion thread whose suggestions are reflected in this module were David H. Adler, David Golden, Michael G. Schwern and Tels. Fergal Daly also made suggestions in separate communications.

The structure for this module was created with my own hacked-up version of R. Geoffrey Avery's modulemaker utility, based on his CPAN module ExtUtils::ModuleMaker.

AUTHOR ^

James E Keenan. CPAN ID: JKEENAN. jkeenan [at] cpan [dot] org.

COPYRIGHT ^

Copyright 2005-06 James E Keenan.

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

The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO ^

perl(1). IO::Capture; IO::Capture::Stdout; IO::Capture::Overview. Test::Simple; Test::More.

syntax highlighting: