Struct ContextGuard 

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

RAII-style guard for temporarily retaining a variable context.

The guard object is created by VariableSet::push_context.

Methods from Deref<Target = VariableSet>

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

Pushes a new context to this variable set.

This function returns a scope guard that will pop the context when dropped. The guard provides a mutable reference to the variable set, allowing variables to be added or modified within the context.

Note that the guard does not provide access to the whole environment that contains the variable set. If you need access to the environment, use Env::push_context instead.

pub fn get<N>(&self, name: &N) -> Option<&Variable>

where String: Borrow<N>, N: Hash + Eq + ?Sized,

Gets a reference to the variable with the specified name.

This method searches for a variable of the specified name and returns a reference to it if found. If variables with the same name are defined in multiple contexts, the one in the topmost context is considered visible and returned. To limit the search to the local context, use get_scoped.

You cannot retrieve positional parameters using this function. See positional_params.

pub fn get_scoped<N>(&self, name: &N, scope: Scope) -> Option<&Variable>

where String: Borrow<N>, N: Hash + Eq + ?Sized,

Returns a reference to the variable with the specified name.

This method searches for a variable of the specified name and returns a reference to it if found. The scope parameter determines the context the variable is searched for:

• If the scope is Global, the variable is searched for in all contexts from the topmost to the base context.
• If the scope is Local, the variable is searched for from the topmost to the topmost regular context.
• If the scope is Volatile, the variable is searched for in volatile contexts above the topmost regular context.

get_scoped with Scope::Global is equivalent to get.

You cannot retrieve positional parameters using this function. See positional_params.

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

Gets a mutable reference to the variable with the specified name.

You use this method to create or modify a variable. This method searches for a variable of the specified name, and returns a mutable reference to it if found. Otherwise, this method creates a new variable and returns a mutable reference to it. The scope parameter determines the context the variable is searched for or created in:

• If the scope is Global, an existing variable is searched for like get. If a variable is found in a regular context, the variable is returned. If there is no variable, a new defaulted variable is created in the base context and returned.
  • If a variable is in a volatile context, this method removes the variable from the volatile context and continues searching for a variable in a lower context. If a variable is found in a regular context, it is replaced with the variable removed from the volatile context. Otherwise, the removed variable is moved to the base context. In either case, the moved variable is returned.
• If the scope is Local, the behavior is the same as Global except that any contexts below the topmost regular context are ignored. If a variable is found in the topmost regular context, the variable is returned. If there is no variable, a new defaulted variable is created in the topmost regular context and returned.
  • If a variable is in a volatile context above the topmost regular context, the variable is moved to the topmost regular context, overwriting the existing variable if any. The moved variable is returned.
• If the scope is Volatile, this method requires the topmost context to be volatile. Otherwise, this method will panic! If the topmost context is volatile, an existing variable is searched for like get. If a variable is found in the topmost context, the variable is returned. If a variable is found in a lower context, the variable is cloned to the topmost context and returned. If there is no variable, a new defaulted variable is created in the topmost context and returned.

You cannot modify positional parameters using this method. See positional_params_mut.

This method does not apply the AllExport option. You need to export the variable yourself, or use Env::get_or_create_variable to get the option applied automatically.

pub fn get_scalar<N>(&self, name: &N) -> Option<&str>

where String: Borrow<N>, N: Hash + Eq + ?Sized,

Gets the value of the specified scalar variable.

This is a convenience function that retrieves the value of the specified scalar variable. If the variable is unset or an array, this method returns None.

Note that this function does not apply any Quirk the variable may have. Use Variable::expand to apply quirks.

pub fn unset<'a>( &'a mut self, name: &'a str, scope: Scope, ) -> Result<Option<Variable>, UnsetError<'a>>

Unsets a variable.

If successful, the return value is the previous value. If the specified variable is read-only, this function fails with UnsetError.

The behavior of unsetting depends on the scope:

• If the scope is Global, this function removes the variable from all contexts.
• If the scope is Local, this function removes the variable from the topmost regular context and any volatile context above it.
• If the scope is Volatile, this function removes the variable from any volatile context above the topmost regular context.

In any case, this function may remove a variable from more than one context, in which case the return value is the value in the topmost context. If any of the removed variables is read-only, this function fails with UnsetError and does not remove any variable.

You cannot modify positional parameters using this function. See positional_params_mut.

pub fn iter(&self, scope: Scope) -> Iter<'_>

Returns an iterator of variables.

The scope parameter chooses variables returned by the iterator:

• Global: all variables
• Local: variables in the topmost regular context or above.
• Volatile: variables above the topmost regular context

In all cases, the iterator ignores variables hidden by another.

The order of iterated variables is unspecified.

pub fn env_c_strings(&self) -> Vec<CString>

Returns environment variables in a new vector of C strings.

This function returns a vector of C strings that represent the currently defined environment variables. The strings are of the form name=value. For variables that have an array value, the array items are concatenated with a : between them to represent the value in a single string.

This function ignores variables that have a name that contains a =, since the = would be misinterpreted as the name-value separator.

Currently, this function also ignores the variable if the name or value contains a nul character, but this behavior may be changed in the future.

pub fn extend_env<I, K, V>(&mut self, vars: I)

where I: IntoIterator<Item = (K, V)>, K: Into<String>, V: Into<String>,

Imports environment variables from an iterator.

The argument iterator must yield name-value pairs. This function assigns the values to the variable set, overwriting existing variables. The variables are exported.

If an assignment fails because of an existing read-only variable, this function ignores the error and continues to the next assignment.

pub fn init(&mut self)

Initializes default variables.

This function assigns the following variables to self:

• IFS=' \t\n'
• OPTIND=1
• PS1='$ '
• PS2='> '
• PS4='+ '
• LINENO (with no value, but has its quirk set to Quirk::LineNumber)

The following variables are not assigned by this function as their values cannot be determined independently:

• PPID
• PWD

This function ignores any assignment errors.

pub fn positional_params(&self) -> &PositionalParams

Returns a reference to the positional parameters.

Every regular context starts with an empty array of positional parameters, and volatile contexts cannot have positional parameters. This function returns a reference to the positional parameters of the topmost regular context.

See also positional_params_mut.

pub fn positional_params_mut(&mut self) -> &mut PositionalParams

Returns a mutable reference to the positional parameters.

Every regular context starts with an empty array of positional parameters, and volatile contexts cannot have positional parameters. This function returns a reference to the positional parameters of the topmost regular context.

Trait Implementations

impl<'a> Debug for ContextGuard<'a>

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

Formats the value using the given formatter.

impl Deref for ContextGuard<'_>

type Target = VariableSet

The resulting type after dereferencing.

fn deref(&self) -> &VariableSet

Dereferences the value.

impl DerefMut for ContextGuard<'_>

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

Mutably dereferences the value.

impl Drop for ContextGuard<'_>

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

fn drop(&mut self)

Executes the destructor for this type.