Struct Shell 

pub struct Shell<SE: ShellExtensions = DefaultShellExtensions> { /* private fields */ }

Represents an instance of a shell.

Type Parameters

• SE - The shell extensions implementation to use. These extensions are statically injected into the shell at compile time to provide custom behavior. When unspecified, defaults to DefaultShellExtensions, which provide standard behavior.

Implementations

impl Shell

pub fn builder() -> ShellBuilder<DefaultShellExtensions, Empty>

Create an instance of Shell using the builder syntax

pub fn builder_with_extensions<SE: ShellExtensions>() -> ShellBuilder<SE, Empty>

Create an instance of Shell using the builder syntax, with custom extensions.

impl<SE: ShellExtensions> 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 const fn builtins(&self) -> &HashMap<String, Registration<SE>>

Returns the registered builtins for the shell.

impl<SE: ShellExtensions> Shell<SE>

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.

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.

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.

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).

impl<SE: ShellExtensions> Shell<SE>

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

Generates command completions for the shell.

Arguments

• input - The input string to generate completions for.
• position - The position in the input string to generate completions at.

impl<SE: ShellExtensions> Shell<SE>

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.

impl<SE: ShellExtensions> Shell<SE>

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.

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.

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.

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.

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.

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

Evaluate the given arithmetic expression, returning the result.

impl<SE: ShellExtensions> Shell<SE>

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.

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.

impl<SE: ShellExtensions> Shell<SE>

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.

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 in the shell’s current default PATH, matching the given glob pattern.

Arguments

• required_glob_pattern - The glob pattern to match against.

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 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.

impl<SE: ShellExtensions> Shell<SE>

pub const fn funcs(&self) -> &FunctionEnv

Returns the function definition environment for this shell.

pub const 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 “()”.

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

Invokes a function defined in this shell, returning the resulting exit status.

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.

impl<SE: ShellExtensions> Shell<SE>

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.

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

Adds a command to history.

impl<SE: ShellExtensions> Shell<SE>

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).

Arguments

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

impl<SE: ShellExtensions> Shell<SE>

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.

impl<SE: ShellExtensions> Shell<SE>

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

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

impl<SE: ShellExtensions> Shell<SE>

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.

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.

pub const 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.

impl<SE: ShellExtensions> Shell<SE>

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

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

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

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

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

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

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

Composes the shell’s continuation prompt.

impl<SE: ShellExtensions> Shell<SE>

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.

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.

impl<SE: ShellExtensions> Shell<SE>

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.

impl<SE: ShellExtensions> Shell<SE>

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 const 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.

impl<SE: ShellExtensions> Shell<SE>

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.

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> AsMut<Shell<SE>> for Shell<SE>

fn as_mut(&mut self) -> &mut Self

Converts this type into a mutable reference of the (usually inferred) input type.

impl<SE: ShellExtensions> AsRef<Shell<SE>> for Shell<SE>

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl<SE: ShellExtensions> Clone for Shell<SE>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<SE: ShellExtensions> Default for Shell<SE>

fn default() -> Self

Returns the “default value” for a type.

impl<SE: ShellExtensions> ShellState for Shell<SE>

fn is_subshell(&self) -> bool

Returns whether or not this shell is a subshell.

fn last_stopwatch_time(&self) -> SystemTime

Returns the last “SECONDS” captured time.

fn last_stopwatch_offset(&self) -> u32

Returns the last “SECONDS” offset requested.

fn env(&self) -> &ShellEnvironment

Returns the shell environment containing variables.

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

Returns a mutable reference to the shell environment.

fn options(&self) -> &RuntimeOptions

Returns the shell’s runtime options.

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

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

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

Returns the shell’s aliases.

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

Returns a mutable reference to the shell’s aliases.

fn jobs(&self) -> &JobManager

Returns the shell’s job manager.

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

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

fn traps(&self) -> &TrapHandlerConfig

Returns the shell’s trap handler configuration.

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

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

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

Returns the shell’s directory stack.

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

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

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

Returns the statuses of commands in the last pipeline.

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

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

fn program_location_cache(&self) -> &PathCache

Returns the shell’s program location cache.

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

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

fn completion_config(&self) -> &Config

Returns the shell’s completion configuration.

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

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

fn open_files(&self) -> &OpenFiles

Returns the shell’s open files.

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

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

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

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

fn depth(&self) -> usize

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

fn call_stack(&self) -> &CallStack

Returns the call stack for the shell.

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

Returns the shell’s history, if it exists.

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

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

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

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

fn last_exit_status(&self) -> u8

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

fn set_last_exit_status(&mut self, status: u8)

Updates the last exit status.

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

Returns the key bindings helper for the shell.

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

Sets the key bindings helper for the shell.

fn working_dir(&self) -> &Path

Returns the shell’s current working directory.

fn working_dir_mut(&mut self) -> &mut PathBuf

Returns a mutable reference to the shell’s current working directory. This is only accessible within the crate.

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

Returns the product display name for this shell.