Struct Shell

pub struct Shell {

    pub traps: TrapHandlerConfig,
    pub open_files: OpenFiles,
    pub working_dir: PathBuf,
    pub env: ShellEnvironment,
    pub funcs: FunctionEnv,
    pub options: RuntimeOptions,
    pub aliases: HashMap<String, String>,
    pub last_exit_status: u8,
    pub last_pipeline_statuses: Vec<u8>,
    pub shell_name: Option<String>,
    pub positional_parameters: Vec<String>,
    pub shell_product_display_str: Option<String>,
    pub directory_stack: Vec<PathBuf>,
    pub completion_config: Config,
    pub builtins: HashMap<String, Registration>,
    pub key_bindings: Option<Arc<Mutex<dyn KeyBindings>>>,
    /* private fields */
}

Represents an instance of a shell.

Fields

traps: TrapHandlerConfig

Trap handler configuration for the shell.

open_files: OpenFiles

Manages files opened and accessible via redirection operators.

working_dir: PathBuf

The current working directory.

env: ShellEnvironment

The shell environment, containing shell variables.

funcs: FunctionEnv

Shell function definitions.

options: RuntimeOptions

Runtime shell options.

aliases: HashMap<String, String>

Shell aliases.

last_exit_status: u8

The status of the last completed command.

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)

shell_product_display_str: Option<String>

Detailed display string for the shell

directory_stack: Vec<PathBuf>

Directory stack used by pushd et al.

completion_config: Config

Completion configuration.

builtins: HashMap<String, Registration>

Shell built-in commands.

key_bindings: Option<Arc<Mutex<dyn KeyBindings>>>

Key bindings for the shell, optionally implemented by an interactive shell.

Implementations

impl Shell

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 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 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 last_result(&self) -> u8

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

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 get_history_file_path(&self) -> Option<PathBuf>

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

pub fn get_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 get_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 async fn get_completions( &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 get_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 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.

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.

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

Performs copy-assignment from source.