---
name: "IO::Capture::Stdout"
section: "3pm"
platform: "linux"
package: "libio-capture-perl"
version: "0.05-6"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/IO::Capture::Stdout"
---

# IO::Capture::Stdout(3pm)

Capture any output sent to STDOUT

## NAME

IO::Capture::Stdout - Capture any output sent to STDOUT

## SYNOPSIS

```
    # Generic example (Just to give the overall view)
    use IO::Capture::Stdout;
    $capture = IO::Capture::Stdout->new();
    $capture->start();          # STDOUT Output captured
    print STDOUT "Test Line One\n";
    print STDOUT "Test Line Two\n";
    print STDOUT "Test Line Three\n";
    $capture->stop();           # STDOUT output sent to wherever it was before 'start'
    # In 'scalar context' returns next line
    $line = $capture->read;
    print "$line";         # prints "Test Line One"
    $line = $capture->read;
    print "$line";         # prints "Test Line Two"
    # move line pointer to line 1
    $capture->line_pointer(1);
    $line = $capture->read;
    print "$line";         # prints "Test Line One"
    # Find out current line number
    $current_line_position = $capture->line_pointer;
    # In 'List Context' return an array(list)
    @all_lines = $capture->read;
    # More useful example 1 - "Using in module tests"
    #  Note: If you don't want to make users install
    #        the IO::Capture module just for your tests,
    #        you can just install in the t/lib directory
    #        of your module and use the lib pragma in
    #        your tests.
    use lib "t/lib";
    use IO::Capture::Stdout;
    use Test::More;
    my $capture =  IO::Capture::Stdout->new;
    $capture->start
    # execute with a bad parameter to make sure get
    # an error.
    ok( ! $test("Bad Parameter") );
    $capture->stop();
```

## DESCRIPTION

The module `"IO::Capture::Stdout"`, is derived from the abstract class `"IO::Capture"`. See IO::Capture. The purpose of the module (as the name suggests) is to capture  any output sent to `"STDOUT"`.  After the capture is stopped, the STDOUT filehandle  will be reset to the previous location. E.g., If previously redirected to a file, when  `"IO::Capture->stop"` is called, output will start going into that file again.

Note:  This module won't work with the perl function, **system()**, or any other operation \
        involving a **fork()**.  If you want to capture the output from a system command,\
        it is faster to use **open()** or back-ticks.

```
       my $output = `/usr/sbin/ls -l 2>&1`;
```

## METHODS

### new

- •

  Creates a new capture object.

- •

  An object can be reused as needed, so will only need to do one of these.

  - •

    Be aware, any data previously captured will be discarded if a new  capture session is started.

### start

- •

  Start capturing data into the `"IO::Capture"` Object.

- •

  Can **not** be called on an object that is already capturing.

- •

  Can **not** be called while STDOUT tied to an object.

- •

  `"undef"` will be returned on an error.

### stop

- •

  Stop capturing data and point STDOUT back to it's previous output location I.e., untie STDOUT

### read

- •

  In *Scalar Context*

  - •

    Lines are read from the buffer at the position of the `"line_pointer"`,  and the pointer is incremented by one.

    ```
        $next_line = $capture->read;
    ```

- •

  In *List Context*

  - •

    The array is returned.  The `"line_pointer"` is not affected.

    ```
        @buffer = $capture->read;
    ```

- •

  Data lines are returned exactly as they were captured.  You may want  to use `"chomp"` on them if you don't want the end of line character(s)

  ```
      while (my $line = $capture->read) {
          chomp $line;
          $cat_line = join '', $cat_line, $line;
      }
  ```

### line\_pointer

- •

  Reads or sets the `"line_pointer"`.

  ```
      my $current_line = $capture->line_pointer;
      $capture->line_pointer(1);
  ```

## SUB-CLASSING

### Adding Features

If you would like to sub-class this module to add a feature (method) or two, here is a couple of easy steps. Also see IO::Capture::Overview.

- 1\.

  Give your package a name

  ```
      package MyPackage;
  ```

- 2\.

  Use this `"IO::Capture::Stdout"` as your base class like this:

  ```
      package MyPackage;
      use base qw/IO::Capture::Stdout/;
  ```

- 3\.

  Add your new method like this

  ```
      package MyPackage;
      use base qw/IO::Capture::Stdout/;
      sub grep {
          my $self = shift;
          for $line (
      }
  ```

## See Also

IO::Capture::Overview

IO::Capture

IO::Capture::Stderr

## AUTHORS

Mark Reynolds reynolds@sgi.com

Jon Morgan jmorgan@sgi.com

## COPYRIGHT

Copyright (c) 2003, Mark Reynolds. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.