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