/ 
Backticks-1.0
River stage one • 1 direct dependent • 1 total dependent
/ Backticks

NAME

Backticks - Use `backticks` like objects

VERSION

Version 1.0

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->success; # Will be true when the 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 'print STDERR "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 "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 'print STDERR "Hello world!"'`->stderr; # Shows 'Hello world'
say `perl -e 'exit 1'`->exitcode;                    # Shows '1'

You can also use the classical 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,
);

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.

`command`

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

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

$obj->run()

Runs (or if the command has already been run, re-runs) the $obj's command, and returns the object.

$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->autodie

Boolean, returns whether or not $obj is configured to die when $obj->success is not true. Defaults to $Backticks::autodie or 0

$obj->chomped

Boolean, returns whether or not $obj is configured to chomp the contents of stderr and stdout. Defaults to $Backticks::chomped or 0

$obj->debug

Boolean, whether or not $obj is configured to print additional debugging output to stderr as commands are processed. Defaults to $Backticks::debug or 0

$obj->command

String, returns the command this object is/was configured to run

$obj->error

String, returns a description of any errors encountered while running the command.

$obj->returncode

Integer, returns the value of $? after running the command.

$obj->stdout

String, returns the contents of STDOUT of the command which was run.

$obj->stderr

String, returns the contents of STDERR of the command which was run.

$obj->coredump

Boolean, whether or not a coredump was created when the command was run. Equivalent to $? & 128

$obj->exitcode

Integer, the exit code returned when the command was run. Equivalent to $? >> 8

$obj->signal

Integer, the signal number returned when the command was run. Equivalent to $? & 127

$obj->success

Boolean, whether or not the command run had an error or return code.

$obj->error_verbose

If the command run for $obj was not successful, this will contain a description of the command which was run, the problem found, and the contents of the command's STDERR.

ACCESSING THE LAST RUN

Any of the instance $obj->method's above can also be called as Backtics->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

CAVEATS

We capture output through redirection to temp files, so you can't use redirection in your backticks or you will get unexpected results. This also means there's a speed penatly as compared to plain perl backticks, but it's the only way to capture both STDOUT and STDERR that worked consistently cross-platform and cross-perl-versions.

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; # Module is still loaded, but `backticks` are perl's built-in
              # ones...  use Backticks->run() or Backticks->new() to create
			  # objects now.

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

use Backticks;
`command`;   # Goes through the Backticks modules and returns an object
qx{command}; # Bypasses the Backticks module, returns a string

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, <kilna at 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 Anthony Kilna.

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.