Struct LocalCommand 

pub struct LocalCommand { /* private fields */ }

Implementations

impl LocalCommand

pub fn new<S>(program: S) -> Self

where S: AsRef<OsStr>,

Examples found in repository

examples/error.rs (line 13)

fn startup(mut commands: Commands) {
    commands.spawn(LocalCommand::new("commandthatdoesnotexist"));
}

examples/simple.rs (line 15)

fn startup(mut commands: Commands) {
    // Choose the command based on the OS
    #[cfg(not(windows))]
    let cmd = LocalCommand::new("sh").args(["-c", "echo Sleeping for 1s && sleep 1 && echo Done"]);
    #[cfg(windows)]
    let cmd = LocalCommand::new("powershell").args(["echo 'Sleeping for 1s'; sleep 1; echo Done"]);

    let id = commands.spawn(cmd).id();
    println!("Spawned the command as entity {id:?}");
}

examples/despawn_on_completion.rs (line 15)

fn startup(mut commands: Commands) {
    // Choose the command based on the OS
    #[cfg(not(windows))]
    let cmd = LocalCommand::new("sh").args(["-c", "echo Sleeping for 1s && sleep 1 && echo Done"]);
    #[cfg(windows)]
    let cmd = LocalCommand::new("powershell").args(["echo 'Sleeping for 1s'; sleep 1; echo Done"]);

    let id = commands.spawn((cmd, Cleanup::DespawnEntity)).id();
    println!("Spawned the command as entity {id:?}");
}

examples/input.rs (line 18)

fn startup(mut commands: Commands) {
    // Choose the command based on the OS
    #[cfg(not(windows))]
    let cmd =
        LocalCommand::new("sh").args(["-c", "echo 'Enter Name:' && read NAME && echo Hello $NAME"]);
    #[cfg(windows)]
    let cmd = LocalCommand::new("powershell")
        .args(["$name = Read-Host 'Enter Name'; echo \"Name Entered: $name\""]);
    let id = commands.spawn(cmd).id();
    println!("Spawned the command as entity {id:?}");
}

examples/retries_and_remove.rs (line 17)

fn startup(mut commands: Commands) {
    // Choose the command based on the OS
    #[cfg(not(windows))]
    let cmd = LocalCommand::new("sh").args(["-c", "echo Sleeping for 1s && sleep 1 && INVALID "]);
    #[cfg(windows)]
    let cmd = LocalCommand::new("cmd").args(["/C", "echo Sleeping for 1s && timeout 1 && INVALID"]);

    let id = commands
        .spawn((cmd, Retry::Attempts(3), Cleanup::RemoveComponents))
        .id();
    println!("Spawned the command as temporary entity {id:?} with 3 retries");
}

examples/kill.rs (line 21)

fn startup(mut commands: Commands) {
    // Choose the command based on the OS
    #[cfg(not(windows))]
    let cmd = LocalCommand::new("sh").args([
        "-c",
        "echo Sleeping for 4s && sleep 4 && echo This should not print or execute && sleep 100",
    ]);
    #[cfg(windows)]
    let cmd = LocalCommand::new("powershell").args([
        "echo 'Sleeping for 4s'; sleep 4; echo 'This should not print or execute'; sleep 100",
    ]);

    let id = commands.spawn(cmd).id();
    println!("Spawned the command as entity {id:?}")
}

Additional examples can be found in:

• examples/retries_and_delay.rs
• examples/retries_and_delay_and_cleanup.rs
• examples/simple_chain.rs
• examples/chain_failure_delay_retries.rs
• examples/chain_retries_delay_cleanup.rs
• examples/chain_failure.rs

pub fn arg<S: AsRef<OsStr>>(self, arg: S) -> Self

Adds an argument to pass to the program.

Only one argument can be passed per use. So instead of:

.arg("-C /path/to/repo")

usage would be:

.arg("-C")
.arg("/path/to/repo")

To pass multiple arguments see args.

Note that the argument is not passed through a shell, but given literally to the program. This means that shell syntax like quotes, escaped characters, word splitting, glob patterns, variable substitution, etc. have no effect.

pub fn args<I, S>(self, args: I) -> Self

where I: IntoIterator<Item = S>, S: AsRef<OsStr>,

Adds multiple arguments to pass to the program.

To pass a single argument see arg.

Note that the arguments are not passed through a shell, but given literally to the program. This means that shell syntax like quotes, escaped characters, word splitting, glob patterns, variable substitution, etc. have no effect.

Examples found in repository

examples/simple.rs (line 15)

fn startup(mut commands: Commands) {
    // Choose the command based on the OS
    #[cfg(not(windows))]
    let cmd = LocalCommand::new("sh").args(["-c", "echo Sleeping for 1s && sleep 1 && echo Done"]);
    #[cfg(windows)]
    let cmd = LocalCommand::new("powershell").args(["echo 'Sleeping for 1s'; sleep 1; echo Done"]);

    let id = commands.spawn(cmd).id();
    println!("Spawned the command as entity {id:?}");
}

examples/despawn_on_completion.rs (line 15)

fn startup(mut commands: Commands) {
    // Choose the command based on the OS
    #[cfg(not(windows))]
    let cmd = LocalCommand::new("sh").args(["-c", "echo Sleeping for 1s && sleep 1 && echo Done"]);
    #[cfg(windows)]
    let cmd = LocalCommand::new("powershell").args(["echo 'Sleeping for 1s'; sleep 1; echo Done"]);

    let id = commands.spawn((cmd, Cleanup::DespawnEntity)).id();
    println!("Spawned the command as entity {id:?}");
}

examples/input.rs (line 18)

fn startup(mut commands: Commands) {
    // Choose the command based on the OS
    #[cfg(not(windows))]
    let cmd =
        LocalCommand::new("sh").args(["-c", "echo 'Enter Name:' && read NAME && echo Hello $NAME"]);
    #[cfg(windows)]
    let cmd = LocalCommand::new("powershell")
        .args(["$name = Read-Host 'Enter Name'; echo \"Name Entered: $name\""]);
    let id = commands.spawn(cmd).id();
    println!("Spawned the command as entity {id:?}");
}

examples/retries_and_remove.rs (line 17)

fn startup(mut commands: Commands) {
    // Choose the command based on the OS
    #[cfg(not(windows))]
    let cmd = LocalCommand::new("sh").args(["-c", "echo Sleeping for 1s && sleep 1 && INVALID "]);
    #[cfg(windows)]
    let cmd = LocalCommand::new("cmd").args(["/C", "echo Sleeping for 1s && timeout 1 && INVALID"]);

    let id = commands
        .spawn((cmd, Retry::Attempts(3), Cleanup::RemoveComponents))
        .id();
    println!("Spawned the command as temporary entity {id:?} with 3 retries");
}

examples/kill.rs (lines 21-24)

fn startup(mut commands: Commands) {
    // Choose the command based on the OS
    #[cfg(not(windows))]
    let cmd = LocalCommand::new("sh").args([
        "-c",
        "echo Sleeping for 4s && sleep 4 && echo This should not print or execute && sleep 100",
    ]);
    #[cfg(windows)]
    let cmd = LocalCommand::new("powershell").args([
        "echo 'Sleeping for 4s'; sleep 4; echo 'This should not print or execute'; sleep 100",
    ]);

    let id = commands.spawn(cmd).id();
    println!("Spawned the command as entity {id:?}")
}

examples/retries_and_delay.rs (line 19)

fn startup(mut commands: Commands) {
    // Choose the command based on the OS
    #[cfg(not(windows))]
    let cmd =
        LocalCommand::new("sh").args(["-c", "echo Sleeping for 1s && sleep 1 && THIS SHOULD FAIL"]);
    #[cfg(windows)]
    let cmd = LocalCommand::new("cmd").args([
        "/C",
        "echo Sleeping for 1s && timeout 1 && THIS SHOULD FAIL",
    ]);

    let id = commands
        .spawn((
            cmd,
            Retry::Attempts(2),
            Delay::Fixed(Duration::from_secs(2)),
        ))
        .id();
    println!("Spawned the command as entity {id:?} with 2 retries and a 2s delay");
}

Additional examples can be found in:

• examples/retries_and_delay_and_cleanup.rs
• examples/simple_chain.rs
• examples/chain_failure_delay_retries.rs
• examples/chain_retries_delay_cleanup.rs
• examples/chain_failure.rs

pub fn env<K, V>(self, key: K, val: V) -> Self

where K: AsRef<OsStr>, V: AsRef<OsStr>,

Inserts or updates an explicit environment variable mapping.

This method allows you to add an environment variable mapping to the spawned process or overwrite a previously set value. You can use LocalCommand::envs to set multiple environment variables simultaneously.

Child processes will inherit environment variables from their parent process by default. Environment variables explicitly set using LocalCommand::env take precedence over inherited variables. You can disable environment variable inheritance entirely using LocalCommand::env_clear or for a single key using LocalCommand::env_remove.

Note that environment variable names are case-insensitive (but case-preserving) on Windows and case-sensitive on all other platforms.

pub fn envs<I, K, V>(self, vars: I) -> Self

where I: IntoIterator<Item = (K, V)>, K: AsRef<OsStr>, V: AsRef<OsStr>,

Inserts or updates multiple explicit environment variable mappings.

This method allows you to add multiple environment variable mappings to the spawned process or overwrite previously set values. You can use LocalCommand::env to set a single environment variable.

Child processes will inherit environment variables from their parent process by default. Environment variables explicitly set using LocalCommand::envs take precedence over inherited variables. You can disable environment variable inheritance entirely using LocalCommand::env_clear or for a single key using LocalCommand::env_remove.

Note that environment variable names are case-insensitive (but case-preserving) on Windows and case-sensitive on all other platforms.

pub fn env_remove<K: AsRef<OsStr>>(self, key: K) -> Self

Removes an explicitly set environment variable and prevents inheriting it from a parent process.

This method will remove the explicit value of an environment variable set via LocalCommand::env or LocalCommand::envs. In addition, it will prevent the spawned child process from inheriting that environment variable from its parent process.

After calling LocalCommand::env_remove, the value associated with its key from LocalCommand::get_envs will be None.

To clear all explicitly set environment variables and disable all environment variable inheritance, you can use LocalCommand::env_clear.

pub fn env_clear(self) -> Self

Clears all explicitly set environment variables and prevents inheriting any parent process environment variables.

This method will remove all explicitly added environment variables set via LocalCommand::env or LocalCommand::envs. In addition, it will prevent the spawned child process from inheriting any environment variable from its parent process.

After calling LocalCommand::env_clear, the iterator from LocalCommand::get_envs will be empty.

You can use LocalCommand::env_remove to clear a single mapping.

pub fn current_dir<P: AsRef<Path>>(self, dir: P) -> Self

Sets the working directory for the child process.

Platform-specific behavior

If the program path is relative (e.g., "./script.sh"), it’s ambiguous whether it should be interpreted relative to the parent’s working directory or relative to current_dir. The behavior in this case is platform specific and unstable, and it’s recommended to use canonicalize to get an absolute program path instead.

pub fn get_program(&self) -> &OsStr

Returns the path to the program that was given to LocalCommand::new.

Examples

use bevy_local_commands::LocalCommand;

let cmd = LocalCommand::new("echo");
assert_eq!(cmd.get_program(), "echo");

Examples found in repository

examples/retries_and_delay.rs (line 45)

fn update(
    mut process_completed_event: MessageReader<ProcessCompleted>,
    query: Query<&LocalCommand, With<Retry>>,
    mut retry_events: MessageReader<RetryEvent>,
) {
    if let Some(process_completed) = process_completed_event.read().last() {
        if let Ok(local_command) = query.get(process_completed.entity) {
            println!(
                "Command {:?} {:?} completed (Success - {})",
                local_command.get_program(),
                local_command.get_args(),
                process_completed.exit_status.success()
            );
        } else {
            println!("Retry component removed from entity, exiting");
            std::process::exit(0);
        }
    }
    for retry_event in retry_events.read() {
        println!("Retry event triggered: {:?}", retry_event);
    }
}

examples/retries_and_delay_and_cleanup.rs (line 46)

fn update(
    mut process_completed_event: MessageReader<ProcessCompleted>,
    query: Query<&LocalCommand, With<Retry>>,
    mut retry_events: MessageReader<RetryEvent>,
) {
    if let Some(process_completed) = process_completed_event.read().last() {
        if let Ok(local_command) = query.get(process_completed.entity) {
            println!(
                "Command {:?} {:?} completed (Success - {})",
                local_command.get_program(),
                local_command.get_args(),
                process_completed.exit_status.success()
            );
        } else {
            println!("Retry component removed from entity, exiting");
            std::process::exit(0);
        }
    }
    for retry_event in retry_events.read() {
        println!("Retry event triggered: {:?}", retry_event);
    }
}

pub fn get_args(&self) -> CommandArgs<'_>

Returns an iterator of the arguments that will be passed to the program.

This does not include the path to the program as the first argument; it only includes the arguments specified with LocalCommand::arg and LocalCommand::args.

Examples

use std::ffi::OsStr;
use bevy_local_commands::LocalCommand;

let mut cmd = LocalCommand::new("echo").arg("first").arg("second");
let args: Vec<&OsStr> = cmd.get_args().collect();
assert_eq!(args, &["first", "second"]);

Examples found in repository

examples/retries_and_delay.rs (line 46)

fn update(
    mut process_completed_event: MessageReader<ProcessCompleted>,
    query: Query<&LocalCommand, With<Retry>>,
    mut retry_events: MessageReader<RetryEvent>,
) {
    if let Some(process_completed) = process_completed_event.read().last() {
        if let Ok(local_command) = query.get(process_completed.entity) {
            println!(
                "Command {:?} {:?} completed (Success - {})",
                local_command.get_program(),
                local_command.get_args(),
                process_completed.exit_status.success()
            );
        } else {
            println!("Retry component removed from entity, exiting");
            std::process::exit(0);
        }
    }
    for retry_event in retry_events.read() {
        println!("Retry event triggered: {:?}", retry_event);
    }
}

examples/retries_and_delay_and_cleanup.rs (line 47)

fn update(
    mut process_completed_event: MessageReader<ProcessCompleted>,
    query: Query<&LocalCommand, With<Retry>>,
    mut retry_events: MessageReader<RetryEvent>,
) {
    if let Some(process_completed) = process_completed_event.read().last() {
        if let Ok(local_command) = query.get(process_completed.entity) {
            println!(
                "Command {:?} {:?} completed (Success - {})",
                local_command.get_program(),
                local_command.get_args(),
                process_completed.exit_status.success()
            );
        } else {
            println!("Retry component removed from entity, exiting");
            std::process::exit(0);
        }
    }
    for retry_event in retry_events.read() {
        println!("Retry event triggered: {:?}", retry_event);
    }
}

pub fn get_envs(&self) -> CommandEnvs<'_>

Returns an iterator of the environment variables explicitly set for the child process.

Environment variables explicitly set using LocalCommand::env, LocalCommand::envs, and LocalCommand::env_remove can be retrieved with this method.

Note that this output does not include environment variables inherited from the parent process.

Each element is a tuple key/value pair (&OsStr, Option<&OsStr>). A None value indicates its key was explicitly removed via LocalCommand::env_remove. The associated key for the None value will no longer inherit from its parent process.

An empty iterator can indicate that no explicit mappings were added or that LocalCommand::env_clear was called. After calling LocalCommand::env_clear, the child process will not inherit any environment variables from its parent process.

Examples

use std::ffi::OsStr;
use bevy_local_commands::LocalCommand;

let mut cmd = LocalCommand::new("ls").env("TERM", "dumb").env_remove("TZ");
let envs: Vec<(&OsStr, Option<&OsStr>)> = cmd.get_envs().collect();
assert_eq!(envs, &[
    (OsStr::new("TERM"), Some(OsStr::new("dumb"))),
    (OsStr::new("TZ"), None)
]);

pub fn get_current_dir(&self) -> Option<&Path>

Returns the working directory for the child process.

This returns None if the working directory will not be changed.

Examples

use std::path::Path;
use bevy_local_commands::LocalCommand;

let mut cmd = LocalCommand::new("ls");
assert_eq!(cmd.get_current_dir(), None);
cmd = cmd.current_dir("/bin");
assert_eq!(cmd.get_current_dir(), Some(Path::new("/bin")));

Trait Implementations

impl Component for LocalCommand

where Self: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = ::bevy::ecs::component::StorageType::Table

A constant indicating the storage type used for this component.

type Mutability = Mutable

A marker type to assist Bevy with determining if this component is mutable, or immutable. Mutable components will have Component<Mutability = Mutable>, while immutable components will instead have Component<Mutability = Immutable>.

fn register_required_components( _requiree: ComponentId, required_components: &mut RequiredComponentsRegistrator<'_, '_>, )

Registers required components.

fn clone_behavior() -> ComponentCloneBehavior

Called when registering this component, allowing to override clone function (or disable cloning altogether) for this component.

fn on_add() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_add ComponentHook for this Component if one is defined.

fn on_insert() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_insert ComponentHook for this Component if one is defined.

fn on_replace() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_replace ComponentHook for this Component if one is defined.

fn on_remove() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_remove ComponentHook for this Component if one is defined.

fn on_despawn() -> Option<for<'w> fn(DeferredWorld<'w>, HookContext)>

Gets the on_despawn ComponentHook for this Component if one is defined.

fn map_entities<E>(_this: &mut Self, _mapper: &mut E)

where E: EntityMapper,

Maps the entities on this component using the given EntityMapper. This is used to remap entities in contexts like scenes and entity cloning. When deriving Component, this is populated by annotating fields containing entities with #[entities]

impl Debug for LocalCommand

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

Formats the value using the given formatter.

impl From<Command> for LocalCommand

fn from(command: Command) -> Self

Converts to this type from the input type.

impl From<LocalCommand> for Command

fn from(value: LocalCommand) -> Self

Converts to this type from the input type.