Struct Shell 

pub struct Shell {
    pub traps: TrapHandlerConfig,
    pub env: ShellEnvironment,
    pub options: RuntimeOptions,
    pub jobs: JobManager,
    pub aliases: HashMap<String, String>,
    pub last_pipeline_statuses: Vec<u8>,
    pub shell_name: Option<String>,
    pub positional_parameters: Vec<String>,
    pub directory_stack: Vec<PathBuf>,
    pub completion_config: Config,
    pub program_location_cache: PathCache,
    /* private fields */
}

Represents an instance of a shell.

Fields

traps: TrapHandlerConfig

Trap handler configuration for the shell.

env: ShellEnvironment

The shell environment, containing shell variables.

options: RuntimeOptions

Runtime shell options.

jobs: JobManager

State of managed jobs.

aliases: HashMap<String, String>

Shell aliases.

last_pipeline_statuses: Vec<u8>

The status of each of the commands in the last pipeline.

shell_name: Option<String>

Shell name (a.k.a. $0)

positional_parameters: Vec<String>

Positional parameters stack ($1 and beyond)

directory_stack: Vec<PathBuf>

Directory stack used by pushd et al.

completion_config: Config

Completion configuration.

program_location_cache: PathCache

Shell program location cache.

Implementations

impl Shell

pub fn builder() -> ShellBuilder<Empty>

Create an instance of Shell using the builder syntax

pub async fn new(options: CreateOptions) -> Result<Self, Error>

Returns a new shell instance created with the given options.

Arguments

• options - The options to use when creating the shell.

pub const fn current_line_number(&self) -> u32

Returns the current source line number being processed.

pub const fn version(&self) -> &Option<String>

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

pub const fn last_result(&self) -> u8

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

pub const fn function_call_stack(&self) -> &CallStack

Returns a reference to the current function call stack for the shell.

pub const fn script_call_stack(&self) -> &CallStack

Returns a reference to the current script call stack for the shell.

pub const fn last_exit_status_mut(&mut self) -> &mut u8

Returns a mutable reference to the last exit status.

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

Returns the key bindings helper for the shell.

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

Returns the registered builtins for the shell.

pub fn working_dir(&self) -> &Path

Returns the shell’s current working directory.

pub const fn product_display_str(&self) -> &Option<String>

Returns the product display name for this shell.

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

Returns 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, )

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.

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 const fn last_stopwatch_time(&self) -> SystemTime

Returns the last “SECONDS” captured time.

pub const fn last_stopwatch_offset(&self) -> u32

Returns the last “SECONDS” offset requested.

pub async fn source_script<S: AsRef<str>, 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 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.

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

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

Arguments

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

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

pub fn default_exec_params(&self) -> ExecutionParameters

Returns the default execution parameters for this shell.

pub async fn run_script<S: AsRef<str>, 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.

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 on_exit(&mut self) -> Result<(), Error>

Runs any exit steps for the shell.

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

Compose’s 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.

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.

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

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.

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

Register a builtin to the shell’s environment.

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>

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 ifs(&self) -> Cow<'_, str>

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

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.

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>

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 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 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 stdout(&self) -> impl Write

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

pub fn stderr(&self) -> impl Write

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

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 check_for_completed_jobs(&mut self) -> Result<(), Error>

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

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

Evaluate the given arithmetic expression, returning the result.

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.

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

Returns the shell’s history, if it exists.

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

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

pub const fn is_subshell(&self) -> bool

Returns whether or not this shell is a subshell.

pub const fn depth(&self) -> usize

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

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

Trait Implementations

impl AsMut<Shell> for Shell

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

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

impl AsRef<Shell> for Shell

fn as_ref(&self) -> &Self

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

impl Clone for Shell

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.