Enum ShellForCommand 

pub enum ShellForCommand<'a, SE: ShellExtensions> {
    ParentShell(&'a mut Shell<SE>),
    OwnedShell {
        target: Box<Shell<SE>>,
        parent: &'a mut Shell<SE>,
    },
}

Encapsulates a possibly-owned reference to a Shell for command execution.

Variants

ParentShell(&'a mut Shell<SE>)

The command is run in the same shell as its parent; the provided mutable reference allows modifying the parent shell.

OwnedShell

The command is run in its own owned shell (which is also provided).

Fields

target: Box<Shell<SE>>

The owned shell.

parent: &'a mut Shell<SE>

The parent shell.

Methods from Deref<Target = Shell<SE>>

pub fn register_builtin<S: Into<String>>( &mut self, name: S, registration: Registration<SE>, )

Register a builtin to the shell’s environment, replacing any existing registration with the same name.

Arguments

• name - The in-shell name of the builtin.
• registration - The registration handle for the builtin.

pub fn register_builtin_if_unset<S: Into<String>>( &mut self, name: S, registration: Registration<SE>, )

Register a builtin only if no builtin with that name is already registered.

Arguments

• name - The in-shell name of the builtin.
• registration - The registration handle for the builtin.

pub fn builtin_mut(&mut self, name: &str) -> Option<&mut Registration<SE>>

Tries to retrieve a mutable reference to an existing builtin registration. Returns None if no such registration exists.

Arguments

• name - The name of the builtin to lookup.

pub fn builtins(&self) -> &HashMap<String, Registration<SE>>

Returns the registered builtins for the shell.

pub fn in_sourced_script(&self) -> bool

Returns whether or not the shell is actively executing in a sourced script.

pub fn in_function(&self) -> bool

Returns whether or not the shell is actively executing in a shell function.

pub fn start_interactive_session(&mut self) -> Result<(), Error>

Updates the shell’s internal tracking state to reflect that a new interactive session is being started.

Errors

This currently always succeeds.

pub fn end_interactive_session(&mut self) -> Result<(), Error>

Updates the shell’s internal tracking state to reflect that the current interactive session is ending.

Errors

Returns crate::error::ErrorKind::NotInInteractiveSession if the current call stack frame is not an interactive session.

pub fn start_command_string_mode(&mut self)

Updates the shell’s internal tracking state to reflect that command string mode is being started.

pub fn end_command_string_mode(&mut self) -> Result<(), Error>

Updates the shell’s internal tracking state to reflect that command string mode is ending.

Errors

Returns crate::error::ErrorKind::NotExecutingCommandString if the current call stack frame is not a command string.

pub fn current_shell_args(&self) -> &[String]

Returns the current positional arguments for the shell ($1 and beyond). Influenced by the current call stack.

pub fn current_shell_args_mut(&mut self) -> &mut Vec<String>

Returns a mutable reference to current positional parameters for the shell ($1 and beyond).

pub async fn complete( &mut self, input: &str, cursor: usize, ) -> Result<Completions, Error>

Completes the word at the cursor in a line being edited, with programmable completion (see the completion module).

Arguments

• input - The line being completed.
• cursor - The cursor’s byte offset in the line.

Errors

Returns an error if cursor isn’t a char boundary in input.

pub fn in_progress_completion_options_mut( &mut self, ) -> Option<&mut GenerationOptions>

Returns the options of the programmable completion in progress, if any (e.g. while its completion function runs), which the compopt builtin changes.

pub fn env_str(&self, name: &str) -> Option<Cow<'_, str>>

Tries to retrieve a variable from the shell’s environment, converting it into its string form.

Arguments

• name - The name of the variable to retrieve.

pub fn env_var(&self, name: &str) -> Option<&ShellVariable>

Tries to retrieve a variable from the shell’s environment.

Arguments

• name - The name of the variable to retrieve.

pub fn set_env_global( &mut self, name: &str, var: ShellVariable, ) -> Result<(), Error>

Tries to set a global variable in the shell’s environment.

Arguments

• name - The name of the variable to add.
• var - The variable contents to add.

Errors

Returns crate::error::ErrorKind::MissingScopeForNewVariable if the environment has no global scope.

pub fn default_exec_params(&self) -> ExecutionParameters

Returns the default execution parameters for this shell.

pub async fn source_script<S: Into<String>, P: AsRef<Path>, I: Iterator<Item = S>>( &mut self, path: P, args: I, params: &ExecutionParameters, ) -> Result<ExecutionResult, Error>

Source the given file as a shell script, returning the execution result.

Arguments

• path - The path to the file to source.
• args - The arguments to pass to the script as positional parameters.
• params - Execution parameters.

Errors

• crate::error::ErrorKind::FailedSourcingFile if the file cannot be opened or is a directory.

pub async fn run_string<S: Into<String>>( &mut self, command: S, source_info: &SourceInfo, params: &ExecutionParameters, ) -> Result<ExecutionResult, Error>

Executes the given string as a shell program, returning the resulting exit status.

Arguments

• command - The command to execute.
• source_info - Information about the source of the command text.
• params - Execution parameters.

Errors

Parse and execution errors are not returned. They are displayed on the shell’s stderr and folded into the exit status of the returned result.

pub async fn run_dash_c_command<S: Into<String>>( &mut self, command: S, ) -> Result<ExecutionResult, Error>

Executes the given command, provided to a shell executable on the command line (i.e., via -c).

It is expected that the shell will not be used for any further execution after this command; this function will perform any necessary shell exit handling.

Arguments

• command - The command to execute.

Errors

Returns crate::error::ErrorKind::NotExecutingCommandString if the command string frame is no longer the current call stack frame once the command finishes. Errors from the command itself are handled as in Self::run_string.

pub async fn run_script<S: Into<String>, P: AsRef<Path>, I: Iterator<Item = S>>( &mut self, script_path: P, args: I, ) -> Result<ExecutionResult, Error>

Executes the given script file, returning the resulting exit status.

It is expected that the shell will not be used for any further execution after this command; this function will perform any necessary shell exit handling.

Arguments

• script_path - The path to the script file to execute.
• args - The arguments to pass to the script as positional parameters.

Errors

• crate::error::ErrorKind::FailedSourcingFile if the file cannot be opened or is a directory.
• Errors from the script itself are reported on stderr and folded into the returned exit status.

pub async fn run_program( &mut self, program: Program, params: &ExecutionParameters, ) -> Result<ExecutionResult, Error>

Executes the given parsed shell program, returning the resulting exit status.

Arguments

• program - The program to execute.
• params - Execution parameters.

Errors

Returns the error that aborts execution, such as a failed expansion or redirection. Unlike Self::run_string, the error is neither displayed nor converted to an exit status.

pub fn eval_arithmetic(&mut self, expr: &ArithmeticExpr) -> Result<i64, Error>

Evaluate the given arithmetic expression, returning the result.

Errors

Returns crate::error::ErrorKind::EvalError if evaluation fails, for example on division by zero, a negative exponent, or an unset variable under set -u.

pub fn ifs(&self) -> Cow<'_, str>

Returns the current value of the IFS variable, or the default value if it is not set.

pub async fn basic_expand_string<S: AsRef<str>>( &mut self, params: &ExecutionParameters, s: S, ) -> Result<String, Error>

Applies basic shell expansion to the provided string.

Arguments

• s - The string to expand.

Errors

• crate::error::ErrorKind::WordParseError if the text cannot be parsed as a word.
• crate::error::ErrorKind::BadSubstitution, crate::error::ErrorKind::ExpandingUnsetVariable or crate::error::ErrorKind::CheckedExpansionError if an expansion in it fails, as with a bad substitution or an unset variable under set -u.
• Any error raised by a command substitution or arithmetic expansion inside the text.

pub async fn full_expand_and_split_string<S: AsRef<str>>( &mut self, params: &ExecutionParameters, s: S, ) -> Result<Vec<String>, Error>

Applies full shell expansion and field splitting to the provided string; returns a sequence of fields.

Arguments

• s - The string to expand and split.

Errors

• crate::error::ErrorKind::WordParseError if the text cannot be parsed as a word.
• crate::error::ErrorKind::BadSubstitution, crate::error::ErrorKind::ExpandingUnsetVariable or crate::error::ErrorKind::CheckedExpansionError if an expansion in it fails, as with a bad substitution or an unset variable under set -u.
• Any error raised by a command substitution or arithmetic expansion inside the text.

pub fn set_working_dir( &mut self, target_dir: impl AsRef<Path>, ) -> Result<(), Error>

Sets the shell’s current working directory to the given path.

Arguments

• target_dir - The path to set as the working directory.

Errors

• crate::error::ErrorKind::NotADirectory if the path exists but is not a directory.
• crate::error::ErrorKind::IoError if the path’s metadata cannot be read, for example because it does not exist.
• The error from updating PWD or OLDPWD, such as crate::error::ErrorKind::ReadonlyVariable when either is readonly.

pub fn tilde_shorten(&self, s: String) -> String

Tilde-shortens the given string, replacing the user’s home directory with a tilde.

Arguments

• s - The string to shorten.

pub fn find_executables_in_path<'a>( &'a self, filename: &'a str, ) -> impl Iterator<Item = PathBuf> + 'a

Finds executables with the given name in the shell’s current PATH, yielding each match in search order.

Arguments

• filename - The name of the executable to look for.

pub fn find_executables_in_path_with_prefix( &self, filename_prefix: &str, case_insensitive: bool, ) -> impl Iterator<Item = PathBuf>

Finds executables in the shell’s current default PATH, with filenames matching the given prefix.

Arguments

• filename_prefix - The prefix to match against executable filenames.

pub fn find_first_executable_in_path<S: AsRef<str>>( &self, candidate_name: S, ) -> Option<PathBuf>

Determines whether the given filename is the name of an executable in one of the directories in the shell’s current PATH. If found, returns the path.

Arguments

• candidate_name - The name of the file to look for.

pub fn find_first_executable_in_path_using_cache<S: AsRef<str>>( &mut self, candidate_name: S, ) -> Option<PathBuf>

where String: From<S>,

Uses the shell’s hash-based path cache to check whether the given filename is the name of an executable in one of the directories in the shell’s current PATH. If found, ensures the path is in the cache and returns it.

Arguments

• candidate_name - The name of the file to look for.

pub fn resolve_command_in_path<S: AsRef<str>>( &self, candidate_name: S, ) -> Option<PathBuf>

Resolves a command name by searching the shell’s current PATH.

Unlike Self::find_first_executable_in_path, a non-executable entry in the PATH resolves as the command; the shell reports it as the command and then fails to run it. See pathsearch::resolve_command.

Arguments

• candidate_name - The name of the command to resolve.

pub fn resolve_command_in_path_using_cache<S: AsRef<str>>( &mut self, candidate_name: S, ) -> Option<PathBuf>

where String: From<S>,

Like Self::resolve_command_in_path, but consults the shell’s hash-based path cache first and caches whatever a search turns up.

Arguments

• candidate_name - The name of the command to resolve.

pub fn absolute_path(&self, path: impl AsRef<Path>) -> PathBuf

Gets the absolute form of the given path.

Arguments

• path - The path to get the absolute form of.

pub fn replace_open_files( &mut self, open_fds: impl Iterator<Item = (ShellFd, OpenFile)>, )

Replaces the shell’s currently configured open files with the given set. Typically only used by exec-like builtins.

Arguments

• open_files - The new set of open files to use.

pub fn funcs(&self) -> &FunctionEnv

Returns the function definition environment for this shell.

pub fn funcs_mut(&mut self) -> &mut FunctionEnv

Returns a mutable reference to the function definition environment for this shell.

pub fn undefine_func(&mut self, name: &str) -> bool

Tries to undefine a function in the shell’s environment. Returns whether or not a definition was removed.

Arguments

• name - The name of the function to undefine.

pub fn define_func( &mut self, name: impl Into<String>, definition: FunctionDefinition, source_info: &SourceInfo, )

Defines a function in the shell’s environment. If a function already exists with the given name, it is replaced with the new definition.

Arguments

• name - The name of the function to define.
• definition - The function’s definition.
• source_info - Source information for the function definition.

pub fn func_mut(&mut self, name: &str) -> Option<&mut Registration>

Tries to return a mutable reference to the registration for a named function. Returns None if no such function was found.

Arguments

• name - The name of the function to lookup

pub fn define_func_from_str( &mut self, name: impl Into<String>, body_text: &str, ) -> Result<(), Error>

Tries to define a function in the shell’s environment using the given string as its body.

Arguments

• name - The name of the function
• body_text - The body of the function, expected to start with “()”.

Errors

Returns crate::error::ErrorKind::FunctionParseError if body_text is not a valid function body (() followed by a compound command).

pub async fn invoke_function<N: AsRef<str>, I: IntoIterator<Item = A>, A: AsRef<str>>( &mut self, name: N, args: I, params: ExecutionParameters, ) -> Result<ExecutionResult, Error>

Invokes a function defined in this shell, returning its execution result.

Arguments

• name - The name of the function to invoke.
• args - The arguments to pass to the function.
• params - Execution parameters to use for the invocation.

Errors

• crate::error::ErrorKind::FunctionNotFound if no function has the given name.
• crate::error::ErrorKind::Unimplemented if the function’s execution is stopped (job control).
• Any error raised while running the function body, such as crate::error::ErrorKind::MaxFunctionCallDepthExceeded.

pub fn history_file_path(&self) -> Option<PathBuf>

Returns the path to the history file used by the shell, if one is set.

pub fn history_time_format(&self) -> Option<String>

Returns the path to the history file used by the shell, if one is set.

pub fn save_history(&mut self) -> Result<(), Error>

Saves history back to any backing storage.

Errors

Returns crate::error::ErrorKind::IoError if the history file cannot be opened or written.

pub fn add_to_history(&mut self, command: &str) -> Result<(), Error>

Adds a command to history. Like bash, an interactive shell leaves it out or makes room for it as the colon-separated values of HISTCONTROL say:

• ignorespace: leave it out if it starts with a space.
• ignoredups: leave it out if it’s the same as the last entry.
• ignoreboth: both of those.
• erasedups: first remove any earlier entries the same as it.

Errors

This currently always succeeds; the Result leaves room for history backends that can fail.

pub async fn load_config( &mut self, profile_behavior: &ProfileLoadBehavior, rc_behavior: &RcLoadBehavior, ) -> Result<(), Error>

Loads and executes standard shell configuration files (i.e., rc and profile), and then loads the history file (if command history is enabled). History is loaded last since the configuration files may change HISTFILE.

Arguments

• profile_behavior - Behavior for loading profile files.
• rc_behavior - Behavior for loading rc files.

Errors

• crate::error::ErrorKind::FailedSourcingFile if a profile or rc file exists but cannot be read, or is a directory.
• crate::error::ErrorKind::Unimplemented for a non-interactive, non-login shell with BASH_ENV (or ENV in sh mode) set.
• Failure to load the history file is not an error.

pub fn stdout(&self) -> impl Write + 'static

Returns a value that can be used to write to the shell’s currently configured standard output stream using write! et al.

pub fn stderr(&self) -> impl Write + 'static

Returns a value that can be used to write to the shell’s currently configured standard error stream using write! et al.

pub fn display_error( &self, file: &mut impl Write, err: &Error, ) -> Result<(), Error>

Displays the given error to the user, using the shell’s error display mechanisms.

Arguments

• file_table - The open file table to use for any file descriptor references.
• err - The error to display.

Errors

Returns crate::error::ErrorKind::IoError if writing to file fails.

pub fn check_for_completed_jobs(&mut self) -> Result<(), Error>

Checks for completed jobs in the shell, reporting any changes found.

Errors

Returns crate::error::ErrorKind::IoError if reporting a finished job on stderr fails.

pub fn parse<R: Read>(&self, reader: R) -> Result<Program, ParseError>

Parses the given reader as a shell program, returning the resulting Abstract Syntax Tree for the program.

Errors

• shrub_parser::ParseError::Tokenizing if the input cannot be tokenized.
• shrub_parser::ParseError::ParsingNear or shrub_parser::ParseError::ParsingAtEndOfInput if the input is not a valid program.

pub fn parse_string<S: Into<String>>(&self, s: S) -> Result<Program, ParseError>

Parses the given string as a shell program, returning the resulting Abstract Syntax Tree for the program.

Arguments

• s - The string to parse as a program.

Errors

• shrub_parser::ParseError::Tokenizing if the input cannot be tokenized.
• shrub_parser::ParseError::ParsingNear or shrub_parser::ParseError::ParsingAtEndOfInput if the input is not a valid program.

pub fn parser_options(&self) -> ParserOptions

Returns the options that should be used for parsing shell programs; reflects the current configuration state of the shell and may change over time.

pub async fn compose_precmd_prompt(&mut self) -> Result<String, Error>

Composes the shell’s post-input, pre-command prompt, applying all appropriate expansions.

Errors

Returns crate::error::ErrorKind::WordParseError if the value of PS0 is not a valid prompt string, or the error from any expansion in it, such as a failing command substitution.

pub async fn compose_prompt(&mut self) -> Result<String, Error>

Composes the shell’s prompt, applying all appropriate expansions.

Errors

Returns crate::error::ErrorKind::WordParseError if the value of PS1 is not a valid prompt string, or the error from any expansion in it, such as a failing command substitution.

pub async fn compose_alt_side_prompt(&mut self) -> Result<String, Error>

Composes the shell’s alternate-side prompt, applying all appropriate expansions.

Errors

Returns crate::error::ErrorKind::WordParseError if the value of SHRUB_PS_ALT is not a valid prompt string, or the error from any expansion in it, such as a failing command substitution.

pub async fn compose_continuation_prompt(&mut self) -> Result<String, Error>

Composes the shell’s continuation prompt.

Errors

Returns crate::error::ErrorKind::WordParseError if the value of PS2 is not a valid prompt string, or the error from any expansion in it, such as a failing command substitution.

pub fn set_edit_buffer( &mut self, contents: String, cursor: usize, ) -> Result<(), Error>

Updates the shell state to reflect the given edit buffer contents.

Arguments

• contents - The contents of the edit buffer.
• cursor - The cursor position in the edit buffer.

Errors

Returns crate::error::ErrorKind::MissingScopeForNewVariable if the environment has no global scope to hold READLINE_LINE and READLINE_POINT.

pub fn pop_edit_buffer(&mut self) -> Result<Option<(String, usize)>, Error>

Returns the contents of the shell’s edit buffer, if any. The buffer state is cleared from the shell.

Errors

Returns crate::error::ErrorKind::ReadonlyVariable if READLINE_LINE or READLINE_POINT is readonly and so cannot be unset.

pub async fn on_exit(&mut self) -> Result<(), Error>

Runs any exit steps for the shell.

This currently includes invoking the EXIT trap handler, if any.

Errors

Returns an error if the EXIT trap handler cannot be invoked. Errors raised by the handler’s own commands are reported on stderr and reflected in the exit status instead.

pub fn increment_interactive_line_offset(&mut self, delta: usize)

Increments the interactive line offset in the shell by the indicated number of lines.

Arguments

• delta - The number of lines to increment the current line offset by.

pub fn set_current_cmd(&mut self, cmd: &impl Node)

Updates the currently executing command in the shell.

pub fn save_command_status(&self) -> SavedCommandStatus

Captures the state the last command left behind; see SavedCommandStatus.

pub fn restore_command_status(&mut self, saved: SavedCommandStatus)

Reapplies a snapshot, exit-status change counter included. Consumes it; clone it to put the same one back more than once, e.g. between successive hook functions.

Arguments

• saved - The snapshot to restore.

pub fn apply_errexit_if_enabled(&self, result: &mut ExecutionResult)

Applies errexit semantics to a result if enabled and appropriate. This should be called at “statement boundaries” where errexit should be checked.

Arguments

• result - The execution result to potentially modify.

pub fn is_keyword(&self, s: &str) -> bool

Checks if the given string is a keyword reserved in this shell.

Arguments

• s - The string to check.

pub fn is_subshell(&self) -> bool

Returns whether or not this shell is a subshell.

pub fn last_stopwatch_time(&self) -> SystemTime

Returns the last “SECONDS” captured time.

pub fn last_stopwatch_offset(&self) -> u32

Returns the last “SECONDS” offset requested.

pub fn env(&self) -> &ShellEnvironment

Returns the shell environment containing variables.

pub fn env_mut(&mut self) -> &mut ShellEnvironment

Returns a mutable reference to the shell environment.

pub fn options(&self) -> &RuntimeOptions

Returns the shell’s runtime options.

pub fn options_mut(&mut self) -> &mut RuntimeOptions

Returns a mutable reference to the shell’s runtime options.

pub fn aliases(&self) -> &HashMap<String, String>

Returns the shell’s aliases.

pub fn aliases_mut(&mut self) -> &mut HashMap<String, String>

Returns a mutable reference to the shell’s aliases.

pub fn jobs(&self) -> &JobManager

Returns the shell’s job manager.

pub fn jobs_mut(&mut self) -> &mut JobManager

Returns a mutable reference to the shell’s job manager.

pub fn traps(&self) -> &TrapHandlerConfig

Returns the shell’s trap handler configuration.

pub fn traps_mut(&mut self) -> &mut TrapHandlerConfig

Returns a mutable reference to the shell’s trap handler configuration.

pub fn directory_stack(&self) -> &[PathBuf]

Returns the shell’s directory stack.

pub fn directory_stack_mut(&mut self) -> &mut Vec<PathBuf>

Returns a mutable reference to the shell’s directory stack.

pub fn last_pipeline_statuses(&self) -> &[u8]

Returns the statuses of commands in the last pipeline.

pub fn last_pipeline_statuses_mut(&mut self) -> &mut Vec<u8>

Returns a mutable reference to the statuses of commands in the last pipeline.

pub fn program_location_cache(&self) -> &PathCache

Returns the shell’s program location cache.

pub fn program_location_cache_mut(&mut self) -> &mut PathCache

Returns a mutable reference to the shell’s program location cache.

pub fn completion_config(&self) -> &Config

Returns the shell’s completion configuration.

pub fn completion_config_mut(&mut self) -> &mut Config

Returns a mutable reference to the shell’s completion configuration.

pub fn open_files(&self) -> &OpenFiles

Returns the shell’s open files.

pub fn open_files_mut(&mut self) -> &mut OpenFiles

Returns a mutable reference to the shell’s open files.

pub fn current_shell_name(&self) -> Option<Cow<'_, str>>

Returns the current name of the shell ($0). Influenced by the current call stack.

pub fn depth(&self) -> usize

Returns the current subshell depth; 0 is returned if this shell is not a subshell.

pub fn call_stack(&self) -> &CallStack

Returns the call stack for the shell.

pub fn history(&self) -> Option<&History>

Returns the shell’s history, if it exists.

pub fn history_mut(&mut self) -> Option<&mut History>

Returns a mutable reference to the shell’s history, if it exists.

pub fn version(&self) -> Option<&str>

Returns the shell’s official version string (if available).

pub fn last_exit_status(&self) -> u8

Returns the exit status of the last command executed in this shell.

pub fn set_last_exit_status(&mut self, status: u8)

Updates the last exit status, bumping last_exit_status_change_count. To restore a status rather than set one, use Self::restore_command_status, which puts the counter back too.

pub fn key_bindings(&self) -> Option<&Arc<Mutex<dyn KeyBindings>>>

Returns the key bindings helper for the shell.

pub fn set_key_bindings( &mut self, key_bindings: Option<Arc<Mutex<dyn KeyBindings>>>, )

Sets the key bindings helper for the shell.

pub fn working_dir(&self) -> &Path

Returns the shell’s current working directory.

pub fn product_display_str(&self) -> Option<&str>

Returns the product display name for this shell.

Trait Implementations

impl<SE: ShellExtensions> Deref for ShellForCommand<'_, SE>

type Target = Shell<SE>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<SE: ShellExtensions> DerefMut for ShellForCommand<'_, SE>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.