The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Backticks-v1.0.3
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->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,
    );

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.

$Backticks::chomped

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

$Backticks::debug

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

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.

`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.

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()

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.

$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

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, <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.