The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Backticks-v1.0.9
River stage one • 1 direct dependent • 1 total dependent
++
/ Backticks

NAME

Backticks - Use `backticks` like objects!

SYNOPSIS

This module turns backticks into full objects which you can query in interesting ways.

    use Backticks;

    my $results = `ls -a /`; # Assign a Backticks object to $results

    print $results->stdout;  # Get the command's STDOUT
    print $results->stderr;  # Get the command's STDERR
    print $results->merged;  # Get STDOUT and STDERR together
    print $results->success; # Will be true when command exited clean
    print $results;          # Get the command's STDOUT... the object
                             #   stringifies to the command's output
                             #   so you can use it most places you
                             #   use normal backticks

You can have failed commands automatically die your perl script

    $Backticks::autodie = 1;
    `perl -e 'print STDERR "OUCH!\n"; exit 1'`;

Which dies with the following message:

    Error executing `perl -e 'warn "OUCH!\n"; exit 1'`:
    Failed with non-zero exit code 1
    Error output:
    OUCH!

You can automatically chomp output:

    $Backticks::chomped = 1;
    my $chomped = `perl -e "print qq{Hello\n}"`;

You can even access parameters instantly in object mode by calling methods immediately after the backticks!

    say `echo foo`->stdout;                 # Shows 'foo'
    say `perl -e "warn 'Hello!'"`->stderr;  # Shows 'Hello!'
    say `perl -e "exit 1"`->exitcode;       # Shows '1'

You can also use a perl object-oriented interface instead of using the `backticks` to create objects, the following command is the same as the first one above:

    my $results = Backticks->run("ls -la /");

Alternately, you can create a command and run it later:

    my $command = Backticks->new("ls -la /");
    # ... do some stuff
    $command->run();

Creating commands as an object affords you the opportunity to override Backticks package settings, by passing them as hash-style params:

    $Backticks::chomped = 0;
    my $chomped_out = Backticks->run(
        'echo "Hello there!"',
        'chomped' => 1,
    );

PACKAGE VARIABLES

$Backticks::autodie

If set to 1, then any command which does not have a true success() will cause the Perl process to die. Defaults to 0.

This setting was the original onus for this module. By setting autodie you can change a script which as a bunch of unchecked system calls in backticks to having the results all checked using only two lines of code.

$Backticks::chomped

If set to 1, then STDOUT and STDERR will remove a trailing newline from the captured contents, if present. Defaults to 0.

It's very rare when you get output from a command and you don't want its output chomped, or at least it's rare when chomping will cause a problem.

$Backticks::debug

If set to 1, then additional debugging information will be output to STDERR. Defaults to 0.

If you are running deployment scripts in which the output of every command needs to be logged, this can be a handy way of showing everything about each command which was run.

CLASS METHODS

Backticks->new( 'command', [ %params ] )

Creates a new Backticks object but does not run it yet. %params may contain boolean values for this instance's 'debug', 'autodie' and 'chomped' settings.

Backticks->run( 'command', [ %params ] )

Behaves exactly like Backticks->new(...), but after the object is created it immediately runs the command before returning the object.

`command`

This is a source filter alias for:

    Backticks->run( 'command' )

It will create a new Backticks object, run the command, and return the object complete with results. Since Backticks objects stringify to the STDOUT of the command which was run, the default behavior is very similar to Perl's normal backticks.

OBJECT METHODS

$obj->run()

Runs (or if the command has already been run, re-runs) the $obj's command, and returns the object. Note this is the only object method that can't be called in class context (Backticks->run) to have it work on the last executed command as described in the "Accessing the Last Run" secion below. If you need to re-run the last command, use Backticks->rerun instead.

$obj->rerun()

Re-runs $obj's command, and returns the object.

$obj->reset()

Resets the object back to a state as if the command had never been run

$obj->as_table()

Returns a summary text table about the command.

$obj->command()

Returns a string containing the command that this object is/was configured to run.

$obj->stdout(), $obj->stderr(), $obj->merged()

Returns a string containing the contents of STDOUT or STDERR of the command which was run. If chomped is true, then this value will lack the trailing newline if one happened in the captured output. Merged is the combined output of STDOUT and STDERR.

$obj->returncode(), $obj->exitcode(), $obj->coredump(), $obj->signal()

Returns an integer, indicating a $?-based value at the time the command was run:

returncode = $?
exitcode = $? >> 8
coredump = $? & 128
signal = $? & 127

$obj->error(), $obj->error_verbose()

Returns a string containing a description of any errors encountered while running the command. In the case of error_verbose, it will also contain the command which was run and STDERR's output.

$obj->success()

Returns a 1 or 0, indicating whether or not the command run had an error or return code.

$obj->autodie(), $obj->chomped(), $obj->debug()

Returns a 1 or 0, if the corresponding $Backticks::xxx variable has been overridden within this object (as passed in as parameters during ->new()). Otherwise it will return the value of the corresponding $Backticks::xxx field as default.

ACCESSING THE LAST RUN

Any of the instance $obj->method's above can also be called as Backticks->method and will apply to the last command run through the Backticks module. So:

    `run a command`;
    print Backticks->stderr;  # Will show the STDERR for `run a command`!
    print Backticks->success; # Will show success for it...
    
    $foo = Backticks->run('another command');
    print Backticks->stdout; # Output for the above line

If you want to access the last run object more explicitly, you can find it at:

    $Backticks::last_run

NOTES

No redirection

Since we're not using the shell to open subprocesses (behind the scenes we're using open3) you can't redirect input or output. But that shouldn't be a problem, since getting the redirected output is likely why you're using this module in the first place. ;)

STDERR is captured by default

Since we're capturing STDERR from commands which are run, the default behavior is different from Perl's normal backticks, which will print the subprocess's STDERR output to the perl process's STDERR. In other words, command error streams normally trickle up into Perl's error stream, but won't under this module. You can always just print it yourself:

    warn `command`->stderr;
Source filtering

The overriding of `backticks` is provided by Filter::Simple. Source filtering can be weird sometimes... if you want to use this module in a purely traditional Perl OO style, simply turn off the source filtering as soon as you load the module:

    use Backticks;
    no Backticks;

This way the class is loaded, but `backticks` are Perl-native. You can still use Backticks->run() or Backticks->new() to create objects even after the "no Backticks" statement.

Using Perl's backticks with Backticks

If you want to use Perl's normal backticks functionality in conjunction with this module's `backticks`, simply use qx{...} instead:

    use Backticks;
    `command`;   # Uses the Backticks module, returns an object
    qx{command}; # Bypasses Backticks module, returns a string
Module variable scope

The module's variables are shared everywhere it's used within a perl runtime. If you want to make sure that the setting of a Backticks variable is limited to the scope you're in, you should use 'local':

    local $Backticks::chomped = 1;

This will return $Backticks::chomped to whatever its prior state was once it leaves the block.

AUTHOR

Anthony Kilna, <anthony at kilna.com> - http://anthony.kilna.com

BUGS

Please report any bugs or feature requests to bug-backticks at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Backticks. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Backticks

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2012 Kilna Companies.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.