Module variable 

Items for shell variables

A Variable is a named parameter that can be assigned and exported. It is defined in a context of a variable set. A VariableSet is a stack of contexts that can be pushed and popped. Each context has a map of name-variable pairs that effectively manages the variables.

Variable sets and contexts

The variable set is a component of the shell environment (Env). It contains a non-empty stack of contexts. The first context in the stack is called the base context, and it is always present. Other contexts can be pushed and popped on a last-in-first-out basis.

Each context is a map of name-variable pairs. Variables in a context hide those with the same name in lower contexts. You cannot access such hidden variables until the hiding variables are removed or the context containing them is popped.

There are two types of Contexts: regular and volatile. A regular context is the default context type and may have positional parameters. A volatile context is used for holding temporary variables when executing a built-in or function. The context types and Scope affect the behavior of variable assignment. The base context is always a regular context.

Note that the notion of name-variable pairs is directly implemented in the VariableSet struct, and is not visible in the Context enum.

Context guards

This module provides guards to ensure contexts are pushed and popped correctly. The push function returns a guard that will pop the context when dropped. Implementing Deref and DerefMut, the guard allows access to the borrowed variable set or environment. To push a new context and acquire a guard, use VariableSet::push_context or Env::push_context.

Variables

An instance of Variable represents the value and attributes of a shell variable. Although all the fields of a variable are public, you cannot obtain a mutable reference to a variable from a variable set directly. You need to use VariableRefMut to modify a variable.

Variable names and initial values

This module defines constants for the names and initial values of some variables. The constants are used in the shell initialization process to create and assign the variables. The documentation for each name constant describes the variable’s purpose and initial value.

Examples

use yash_env::variable::{Context, Scope, VariableSet};
let mut set = VariableSet::new();

// Define a variable in the base context
let mut var = set.get_or_new("foo", Scope::Global);
var.assign("hello", None).unwrap();

// Push a new context
let mut guard = set.push_context(Context::default());

// The variable is still visible
assert_eq!(guard.get("foo").unwrap().value, Some("hello".into()));

// Defining a new variable in the new context hides the previous variable
let mut var = guard.get_or_new("foo", Scope::Local);
var.assign("world", None).unwrap();

// The new variable is visible
assert_eq!(guard.get("foo").unwrap().value, Some("world".into()));

// Pop the context
drop(guard);

// The previous variable is visible again
assert_eq!(set.get("foo").unwrap().value, Some("hello".into()));

Re-exports

pub use self::value::Value::Array;

pub use self::value::Value::Scalar;

Structs

AssignError

Error that occurs when assigning a value to a read-only variable.

ContextGuard

RAII-style guard for temporarily retaining a variable context.

EnvContextGuard

RAII-style guard that makes sure a context is popped properly

Iter

Iterator of variables

PositionalParams

Positional parameters

QuotedValue

Wrapper of Value for quoting.

UnsetError

Error that occurs when unsetting a read-only variable

Variable

Definition of a variable.

VariableRefMut

Managed mutable reference to a variable.

VariableSet

Collection of variables.

Enums

Context

Variable context

Expansion

Expanded value of a variable

Quirk

Special characteristics of a variable

Scope

Choice of a context in which a variable is assigned or searched for.

Value

Value of a variable.

Constants

CDPATH

The name of the CDPATH variable

ENV

The name of the ENV variable

HOME

The name of the HOME variable

IFS

The name of the IFS variable

IFS_INITIAL_VALUE

The initial value of the IFS variable (" \t\n")

LINENO

The name of the LINENO variable

OLDPWD

The name of the OLDPWD variable

OPTARG

The name of the OPTARG variable

OPTIND

The name of the OPTIND variable

OPTIND_INITIAL_VALUE

The initial value of the OPTIND variable (1)

PATH

The name of the PATH variable

PPID

The name of the PPID variable

PS1

The name of the PS1 variable

PS2

The name of the PS2 variable

PS4

The name of the PS4 variable

PS1_INITIAL_VALUE_NON_ROOT

The initial value of the PS1 variable for non-root user ("$ ")

PS1_INITIAL_VALUE_ROOT

The initial value of the PS1 variable for root user ("# ")

PS2_INITIAL_VALUE

The initial value of the PS2 variable ("> ")

PS4_INITIAL_VALUE

The initial value of the PS4 variable ("+ ")

PWD

The name of the PWD variable