=head1 NAME Promised::Command - Run a command =head1 SYNOPSIS use Promised::Command; $cmd = Promised::Command->new (['ls', '-a', '/']); $cmd->run->then (sub { return $cmd->wait; })->then (sub { my $result = $_[0]; if ($result->exit_code == 0) { warn "done"; } else { warn "failed"; } }); =head1 DESCRIPTION The C class provides a L-returning command execution interface. =head1 METHODS Following methods are available: =over 4 =item $cmd = Promised::Command->new ($args) Create a new command object. The argument must be an array reference containing a command (zeroth item) and zero or more arguments (first or later items). =item $promise = $cmd->run Start the execution of the command. It returns a L, which is resolved with a result object when the execution is started. This method cannot be invoked multiple times. =item $promise = $cmd->wait Return a L, which is resolved with a result object once the execution of the command has finished. This method can be invoked before the C's promise is resolved, but it must be invoked after the C method is invoked. This method always returns the same promise. The promise is resolved with a result object whose C method returns true even when the exit code of the command is non-zero. Note also that failure to execute the command (e.g. command-not-found error) is also result in resolving the promise with a successful result object whose exit code is non-zero. If the command has terminated by an uncaught signal, the promise is rejected with a result object whose C method returns true. =item $boolean = $cmd->create_process_group =item $cmd->create_process_group ($boolean) Get or set whether a new process group should be created for the command (by C) or not. This method must be invoked before the C method is invoked. If this method is not invoked, the same process group as the main process is used. =item $cmd->wd ($string) =item $string = $cmd->wd Get or set the current working directory for the command as a (system-dependent byte) string. This method must be invoked before the C method is invoked. If this method is not invoked, the current directory is left unchanged (i.e. same as that of the main process). =item $hashref = $cmd->envs Return the environment variables for the command as a reference to the hash of environment name/value byte string pairs. If a value is specified in the hash, an environment variable is set. Otherwise, if an C value is explicitly specified in the hash, the environment variable, if any, is unset. Otherwise, any environment variable of the main process is left unchanged. This method must be invoked before the C method is invoked. =item $stream = $cmd->get_stdin_stream =item $cmd->stdin (SCALARREF) Specify how the standard input is handled. If the C is invoked, a L object that is a writable stream of the input is returned. Any written value (i.e. the argument too the C method of the writer) must be an L (such as L and L). If the stream is aborted, the input is closed as soon as possible (which means not all data might be written, though it does not affect the execution of the child process). If a scalar reference is specified to the C method, the referenced scalar value is written as the input. The referenced value must be a byte string. Only one of these methods must be invoked at most once. These methods must be invoked before the C method is invoked. If these methods are not invoked, the input's handling is left unchanged (i.e. same as the standard input of the main process). =item $stream = $cmd->get_stdout_stream =item $cmd->stdout (SCALARREF) =item $cmd->stdout (CODE) =item $stream = $cmd->get_stderr_stream =item $cmd->stderr (SCALARREF) =item $cmd->stderr (CODE) Specify how the standard output or the standard error output is handled. If the C or C method is invoked, a L object that is a readable byte stream of the output is returned. If the stream is canceled, any remaining data are silently discarded (which does not affect the child process). If a scalar reference is specified to the C or C method, the output is set to the referenced scalar value. If a code reference is specified to the C or C method, the code is invoked with a chunk as the argument whenever the chunk is available, and with an C as the argument when the end of the output is reached. Only one of these methods must be invoked at most once for each of standard output and standard error output. These methods must be invoked before the C method is invoked. If these methods are not invoked, the output's handling is left unchanged (i.e. same as the standard output or the standard error output of the main process). =item $pid = $cmd->pid Return the process ID of the child process (i.e. the command's process). This method can be invoked after the C promise is resolved. Note that there can no longer be the process with the ID or can be a different process with the ID if the command has finished. =item $boolean = $cmd->running Return whether the command is running or not. Note that returning a true value does not mean the command is actually in active; it might be finished but not Ced by this process yet. =item $promise = $cmd->send_signal ($signal) Send a signal to the command's process, if running. The argument must be a string or integer representing the signal, such as C or C<2>, or zero to not send any signal. See C. The method returns a L, which is resolved with a result object whose C method returns the number of processed to which the signal is sent. If the command's process is no longer running, the signal is sent to no process. =item $value = $cmd->propagate_signal =item $cmd->propagate_signal ($value) Get or set whether signals to this (main) process should be propagated to the child (command) process or not. The value can be a non-reference value or an array reference of signal names or an array reference of a pair of signal names. A non-reference value is equivalent to C<['INT', 'QUIT', 'TERM']>. A pair of signal names represents that when the first signal is received by the main process, the second signal should be sent to the child process instead. The value represents the types of the signals to propagate. Signals specified by this method caught by the main process result in terminating the main process after the propagation. This method must be invoked before the C method is invoked. If this method is not invoked, no signal is propagated. If signals are to be propagated, any other signal handling should be done through L to avoid confliction of signal handlers. =item $signal = $cmd->signal_before_destruction =item $cmd->signal_before_destruction ($signal) Get or set the signal (e.g. C or C) which should be sent to the command (child) process if it is still running when the command object is destroyed (i.e. the I<$cmd> object is destroyed without its C method invoked). This feature is useful when the command object can be discarded by unexpected shutdown of the application (e.g. Perl runtime error) but still need to ensure that child process should be terminated. This method must be invoked before the C method is invoked. If this method is not invoked, no signal is sent. =item $seconds = $cmd->timeout =item $cmd->timeout ($seconds) Get or set the timeout from the execution of the command in seconds. If a positive number is specified, the signal specified by the C method is sent to the command's process, if any. Otherwise no timeout is set. This method must be invoked before the C method is invoked. =item $signal = $cmd->timeout_signal =item $cmd->timeout_signal ($signal) Get or set the signal (e.g. C or C) which should be sent when the C seconds has elapsed before the command returns. It is set to C unless explicitly specified. This method must be invoked before the C method is invoked. =item $cmd->abort_signal ($asignal) Set the abort signal (L object from the L respository; the value returned by the C<< $abort_controller->signal >> method) which can be used to send a signal to terminate the process. The signal sent when aborted is specified by the C method. This method must be invoked before the C method is invoked. =back =head1 RESULT OBJECT Promises are resolved with a result object, which has following methods: =over 4 =item $boolean = $result->is_success =item $boolean = $result->is_error Whether the operation has succeded or in error. Note that C<< !!$result->is_success == !!!$result->is_error >> is always true. =item $string = '' . $result Return a short message of the result for the developer. =item $int = $result->exit_code Return the exit code of the command, if applicable, or C<-1> otherwise. =item $int = $result->signal Return the signal which terminates the command, if applicable. =item $boolean = $result->core_dump Return whether there is a core dump or not, if applicable. =item $int = $result->killed Return the number of process to which the signal is sent. Used by C's promise. =item $string = $result->message Return a short error message for the developer, if available. =back =head1 ENVIRONMENT VARIABLE If the environment variable C is set to a true value, debug messages are printed to the standard error output. =head1 SEE ALSO There are related modules: L, L. =head1 DEPENDENCY The module requires Perl 5.10 or later. The module requires L and L. Methods C, C, and C require the L module from the perl-streams repository . =head1 AUTHOR Wakaba . =head1 HISTORY This repository was located at until 2 February, 2022. =head1 LICENSE Copyright 2015-2022 Wakaba . This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =cut