Struct ShellAction 

pub struct ShellAction { /* private fields */ }

A declared command, ready to run as an activity.

Implementations

impl ShellAction

pub fn new(command: &str) -> Result<Self, TemplateError>

Parse command into a runnable action.

Errors

Returns TemplateError when the command is empty, has an unterminated quote or ${, contains a $ naming no parameter, or puts a parameter in program position.

pub const fn with_failure_mode(self, failure_mode: FailureMode) -> Self

Set how a non-zero exit is classified.

pub fn with_environment(self, environment: BTreeMap<String, String>) -> Self

Supply the environment the command runs with.

Additive to nothing: the host’s environment is cleared regardless, so these entries plus super::world::INHERITED_VARIABLE are the command’s whole environment. An entry named PATH here replaces the inherited one, because place_in_declared_world applies these after the inherited value.

pub fn with_working_directory(self, directory: impl Into<PathBuf>) -> Self

Run the command in directory instead of wherever the host happens to be.

Worth setting whenever a command names a relative path. Absent, the command inherits the host process’s working directory, which is a property of how the host was launched and not something a package author can see — so a relative path in a declared command means something the author cannot predict.

pub fn referenced_parameters(&self) -> Vec<String>

The parameter names this command references, sorted.

A caller can compare these against an action’s declared parameters to catch a reference to a parameter that does not exist.

pub async fn run( &self, arguments: &BTreeMap<String, Value>, context: &ActivityContext, ) -> Result<ShellOutcome, ActivityFailure>

Run the command with arguments bound to its parameter references.

Cancellation is tree-wide: the command runs in its own process group, and cancelling the activity terminates that whole group rather than only the direct child, so a command that spawned children does not leave them running.

Output is streamed onto context’s transcript seam line by line as the command writes it (see CommandTranscript), so an operator can read what a command step is printing mid-run. The returned ShellOutcome is unaffected: it still carries the command’s complete stdout and stderr.

Errors

Returns an ActivityFailure when a referenced parameter is missing or unrepresentable (terminal — re-running cannot supply it), when the command cannot be spawned or observed (terminal — the program is absent or unrunnable), when the activity is already cancelled before the command starts (terminal — nothing runs at all), when the command is cancelled while running (terminal), when the host reports an ending that is neither an exit nor a signal (terminal — there is no honest status to report, and see [super::failure::ending_permits_retry] for why an ending this host cannot read is never retried at either executor), or when it exits non-zero or is ended by a signal (classified by the action’s FailureMode, and the signal is named rather than rendered as an exit code alone).

Trait Implementations

impl Clone for ShellAction

fn clone(&self) -> ShellAction

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ShellAction

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.