new

    my $capture = IO::Capture->new( { Key => 'value' } );

All elements from this hash will be added to the object, and will be available for use by children of IO::Capture.

    my $key = $self->{'Key'};

The internal methods used are:

"_initialize()"

"_initialize" is called as soon as the empty object has been blessed. It adds the structure to the object that it will need. The "IO::Capture" module adds the following

    IO::Capture::messages      => []
    IO::Capture::line_pointer  =>  1
    IO::Capture::status        =>  'Ready',  # Busy when capturing
    

start

Start cannot be called if there is already a capture in progress. The "stop" must be called first.

These internal methods are called in this order.

"_check_pre_conditions"

"_check_pre_conditions" is used to make sure all the preconditions are met before starting a capture. The only precondition checked in "IO::Capture", is to insure the "Ready" flag is "on". I.e., There is not already a capture in progress.

If your module needs to make some checks, and you override this method, make sure you call the parent class "_check_pre_conditions" and check the results.

    sub _check_pre_conditions {
        my $self = shift;

        return unless $self->SUPER::_check_pre_conditions;
    

An example of something you might want to check would be, to make sure STDERR is not already tied if you are going to be using "tie" on it.

Must return a boolean true for success, or false for failure. If a failure is indicated, an "undef" will be returned to the calling function, and an remaining private methods for "start" will not be run.

"_save_current_configuration()"

"_save_current_configuration" in "IO::Capture" will save the state of "STDERR", "STDOUT", and $SIG{__WARN__}. They are saved in the hash keys 'IO::Capture::stderr_save', 'IO::Capture::stdout_save', and 'IO::Capture::handler_save'.

    # Save WARN handler
    $self->{'IO::Capture::handler_save'} = $SIG{__WARN__};
    # Dup stdout
    open STDOUT_SAVE, ">&STDOUT";
    # Save ref to dup
    $self->{'IO::Capture::stdout_save'} = *STDOUT_SAVE;
    # Dup stderr
    open STDERR_SAVE, ">&STDOUT";
    # Save ref to dup
    $self->{'IO::Capture::stderr_save'} = *STDERR_SAVE;
    

These saved values can be used in the "_stop" method to restore the original value to any you changed.

    $SIG{__WARN__} = $self->{'IO::Capture::handler_save'};
    STDOUT = $self->{'IO::Capture::stdout_save'};
    STDERR = $self->{'IO::Capture::stderr_save'};
    

Must return a boolean true for success, or false for failure. If a failure is indicated, an "undef" will be returned to the calling function.

"_start"

Start the capture! This is only an abstract method in "IO::Capture". It will print a warning if called. Which should not happen, as the author of the sub-class will always be sure to override it with her/his own. :-)

This is the first of the three you need to define. You will likely use tie here. The included module "IO::Capture:STDx" (see IO::Capture::STDx or other module of your own or from CPAN. You will read it from the tied module and put it into the object in "_retrieve_captured_text". See _retrieve_captured_text

Must return a boolean true for success, or false for failure. If a failure is indicated, an "undef" will be returned to the calling function.

stop

Must return a boolean true for success, or false for failure. If a failure is indicated, an "undef" will be returned to the calling function.

"_retrieve_captured_text()"

Copy any text captured into the object here. For example, The modules in this package tie the filehandle to the (included) "IO::Capture::STDx" to collect the text. The data needs to be read out of the tied object before the filehandle is untied, so that is done here. In short, if you need to do any work before "_stop" is called, do it here. The "_retrieve_capture_text" in this base class just returns true without doing anything.

Must return a boolean true for success, or false for failure. If a failure is indicated, an "undef" will be returned to the calling function. The "_stop" internal method will be called first.

"_stop"

Do what needs to be done to put things back. Such as untie filehandles and put interrupt handlers back to what they were. The default "_stop" method defined in <IO::Capture> won't do anything, so you should.

Must return a boolean true for success, or false for failure. If a failure is indicated, an "undef" will be returned to the calling function.

read

"_read()"

The internal method used to return the captured text. If called in list context, an array will be returned. (Could be a lot if you captured a lot) or called in scalar context, the line pointed to by the line_pointer will be returned and the line_pointer incremented.