NAME

Sys::Cmd::Template - command/process templates for Sys::Cmd

VERSION

0.99.0 (2022-10-05) Development release

SYNOPSIS

use Sys::Cmd::Template qw/cmd_template/;

my $git = cmd_template('git', {
    dir => '/proj/subdir',
    env => { GIT_DIR => '/proj/.git' },
});

# Get command output, raise exception on failure:
$output = $git->run('status');

# Feed command some input, get output as lines,
# raise exception on failure:
@output = $git->run(qw/commit -F -/, { input => 'feedme' });

# Spawn and interact with a process:
$proc = $git->spawn( @subcmd, { encoding => 'iso-8859-3'} );

while (my $line = $proc->stdout->getline) {
    $proc->stdin->print("thanks");
}

my @errors = $proc->stderr->getlines;
$proc->close();     # Done!

# read exit information
$proc->exit();      # exit status
$proc->signal();    # signal
$proc->core();      # core dumped? (boolean)

DESCRIPTION

Sys::Cmd::Template provides "template" objects for system commands. This is useful when you need to make repeated calls to an external binary with the same options or environment settings. "git" and "gpg" are good examples of such commands.

A Sys::Cmd::Template object should represent the common elements of the calls to your external command. The run, runx and spawn methods then merge their arguments and options with these common elements and execute the result with Sys::Cmd.

A single function is exported on demand by this module:

cmd_template( @cmd, [\%opt] ) => Sys::Cmd::Template

Create a new Sys::Cmd::Template object. The first element of @cmd will be looked up using File::Which if it is not found as a relative file name. %opt is an optional hashref containing any of the following key/values:

dir

The working directory the command will be run in.

encoding

An string value identifying the encoding of the input/output file-handles. Has no default but Sys::Cmd will default this to 'utf8'.

env

A hashref containing key/values to be added to the current environment at run-time. If a key has an undefined value then the key is removed from the environment altogether.

input

A string which is fed to each command via its standard input, which is then closed.

Sys::Cmd::Template objects (documented below) can of course be created using the standard new constructor if you prefer that to the cmd_template function:

$proc = Sys::Cmd::Template->new(
    cmd => \@cmd,
    dir => '/',
    env => { SOME => 'VALUE' },
    encoding => 'iso-8859-3',
    input => 'feedme',
);

Note that Sys::Cmd::Template objects created this way will not lookup the command using File::Which the way the cmd_template function does.

CONSTRUCTOR

new(%args) => Sys::Cmd::Template

Create a new Sys::Cmd template object. %args can contain any one of the cmd, dir, encoding, env and input values as defined as attributes below.

ATTRIBUTES

In contrast with Sys::Cmd the attributes defined here can be modified, and the new values will be used on subsequent method calls.

cmd

An array ref containing the command and its arguments.

dir

The working directory the command will be run in.

encoding

An string value identifying the encoding of the input/output file-handles. Defaults to 'utf8'.

env

A hashref containing key/values to be added to the current environment at run-time. If a key has an undefined value then the key is removed from the environment altogether.

input

A string which is fed to the command via its standard input, which is then closed. Most likely you won't ever want to use this, but it is here for completeness.

METHODS

run( @cmd, [\%opt] ) => $output | @output

Append @cmd to the cmd attribute, execute it using Sys::Cmd and return what the command sent to its STDOUT, raising an exception in the event of error. In array context returns a list instead of a plain string.

The command elements can be modified from your objects values with an optional hashref containing the following key/values:

dir

The working directory the command will be run in. Will replace an existing dir attribute.

encoding

An string value identifying the encoding of the input/output file-handles. Defaults to 'utf8'. Will replace an existing dir attribute.

env

A hashref containing key/values to be added to the current environment at run-time. If a key has an undefined value then the key is removed from the environment altogether. Will be merged with an existing env attribute.

input

A string which is fed to the command via its standard input, which is then closed. Will replace an existing input attribute.

runx( @cmd, [\%opt] ) => $outerrput | @outerrput

The same as the run method but with the command's STDERR output appended to the STDOUT output.

spawn( @cmd, [\%opt] ) => Sys::Cmd

Returns a Sys::Cmd object representing the process running @cmd (appended to the cmd attribute), with attributes set according to the optional \%opt hashref.

SEE ALSO

Sys::Cmd

SUPPORT

Bug Reporting

https://rt.cpan.org/Public/Bug/Report.html?Queue=Sys-Cmd

Source Code

git clone git://github.com/mlawren/sys-cmd.git

AUTHOR

Mark Lawrence <nomad@null.net>.

COPYRIGHT AND LICENSE

Copyright (C) 2011-2021 Mark Lawrence <nomad@null.net>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.