Struct yash_env::stack::EnvFrameGuard

pub struct EnvFrameGuard<'a> { /* private fields */ }

RAII-style guard that makes sure a stack frame is popped properly

The guard object is created by Env::push_frame.

Methods from Deref<Target = Env>

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

Returns the value of the $PWD variable if it is correct.

The variable is correct if:

• it is a scalar variable,
• its value is a pathname of the current working directory (possibly including symbolic link components), and
• there is no dot (.) or dot-dot (..) component in the pathname.

pub fn prepare_pwd(&mut self) -> Result<(), PreparePwdError>

Updates the $PWD variable with the current working directory.

If the value of $PWD is correct, this function does not modify it. Otherwise, this function sets the value to self.system.getcwd().

This function is meant for initializing the $PWD variable when the shell starts.

pub fn push_frame(&mut self, frame: Frame) -> EnvFrameGuard<'_>

Pushes a new frame to the runtime execution context stack.

This function is equivalent to self.stack.push(frame), but returns an EnvFrameGuard that allows re-borrowing the Env.

pub fn push_context(&mut self, context: Context) -> EnvContextGuard<'_>

Pushes a new context to the variable set.

This function is equivalent to self.variables.push_context(context_type), but returns an EnvContextGuard that allows re-borrowing the Env.

pub fn clone_with_system(&self, system: Box<dyn System>) -> Env

Clones this environment.

The application-managed parts of the environment are cloned normally. The system-managed parts are replaced with the provided System instance.

pub fn init_variables(&mut self)

Initializes default variables.

This function assigns the following variables to self:

• IFS=' \t\n'
• OPTIND=1
• PS1='$ '
• PS2='> '
• PS4='+ '
• PPID=(parent process ID)
• PWD=(current working directory) (See Env::prepare_pwd)

This function ignores any errors that may occur.

TODO: PS1 should be set to "# " for root users.

pub async fn wait_for_signals(&mut self) -> Rc<[Number]>

Waits for some signals to be caught in the current process.

Returns an array of signals caught.

This function is a wrapper for SharedSystem::wait_for_signals. Before the function returns, it passes the results to TrapSet::catch_signal so the trap set can remember the signals caught to be handled later.

pub async fn wait_for_signal(&mut self, signal: Number)

Waits for a specific signal to be caught in the current process.

This function calls wait_for_signals repeatedly until it returns results containing the specified signal.

pub fn poll_signals(&mut self) -> Option<Rc<[Number]>>

Returns signals that have been caught.

This function is similar to wait_for_signals but does not wait for signals to be caught. Instead, it only checks if any signals have been caught but not yet consumed in the SharedSystem.

pub fn get_tty(&mut self) -> Result<Fd, Errno>

Returns a file descriptor to the controlling terminal.

This function returns self.tty if it is Some FD. Otherwise, it opens /dev/tty and saves the new FD to self.tty before returning it.

pub fn is_interactive(&self) -> bool

Tests whether the current environment is an interactive shell.

This function returns true if and only if:

• the Interactive option is On in self.options, and
• the current context is not in a subshell (no Frame::Subshell in self.stack).

pub fn controls_jobs(&self) -> bool

Tests whether the shell is performing job control.

This function returns true if and only if:

• the Monitor option is On in self.options, and
• the current context is not in a subshell (no Frame::Subshell in self.stack).

pub async fn wait_for_subshell( &mut self, target: Pid, ) -> Result<(Pid, ProcessState), Errno>

Waits for a subshell to terminate, suspend, or resume.

This function waits for a subshell to change its execution state. The target parameter specifies which child to wait for:

• -1: any child
• 0: any child in the same process group as the current process
• pid: the child whose process ID is pid
• -pgid: any child in the process group whose process group ID is pgid

When self.system.wait returned a new state of the target, it is sent to self.jobs (JobList::update_status) before being returned from this function.

If there is no matching target, this function returns Err(Errno::ECHILD).

If the target subshell is not job-controlled, you may want to use wait_for_subshell_to_finish instead.

pub async fn wait_for_subshell_to_finish( &mut self, target: Pid, ) -> Result<(Pid, ExitStatus), Errno>

Wait for a subshell to terminate.

This function is similar to wait_for_subshell, but returns only when the target is finished (either exited or killed by a signal).

Returns the process ID of the awaited process and its exit status.

pub fn update_all_subshell_statuses(&mut self)

Applies all job status updates to jobs in self.jobs.

This function calls self.system.wait repeatedly until all status updates available are applied to self.jobs (JobList::update_status).

Note that updates of subshells that are not managed in self.jobs are lost when you call this function.

pub fn get_or_create_variable<S>( &mut self, name: S, scope: Scope, ) -> VariableRefMut<'_>

where S: Into<String>,

Get an existing variable or create a new one.

This method is a thin wrapper around VariableSet::get_or_new. If the AllExport option is on, the variable is exported before being returned from the method.

You should prefer using this method over VariableSet::get_or_new to make sure that the AllExport option is applied.

pub fn errexit_is_applicable(&self) -> bool

Tests whether the ErrExit option is applicable in the current context.

This function returns true if and only if:

• the ErrExit option is on, and
• the current stack has no Condition frame.

pub fn apply_errexit(&self) -> ControlFlow<Divert>

Returns a Divert if the shell should exit because of the ErrExit shell option.

The function returns Break(Divert::Exit(None)) if the errexit option is applicable and the current self.exit_status is non-zero. Otherwise, it returns Continue(()).

pub fn apply_result(&mut self, result: Result)

Updates the exit status from the given result.

If result is a Break(divert) where divert.exit_status() is Some exit status, this function sets self.exit_status to that exit status.

Trait Implementations

impl<'a> Debug for EnvFrameGuard<'a>

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

Formats the value using the given formatter.

impl Deref for EnvFrameGuard<'_>

type Target = Env

The resulting type after dereferencing.

fn deref(&self) -> &Env

Dereferences the value.

impl DerefMut for EnvFrameGuard<'_>

fn deref_mut(&mut self) -> &mut Env

Mutably dereferences the value.

impl Drop for EnvFrameGuard<'_>

When the guard is dropped, the stack frame that was pushed when creating the guard is popped.

fn drop(&mut self)

Executes the destructor for this type.