Struct conch_runtime::env::Env

pub struct Env<A, IO, FD, L, V, EX, WD, N: Eq + Hash, ERR> { /* fields omitted */ }

A shell environment implementation which delegates work to other environment implementations.

Uses Rc internally. For a possible Send and Sync implementation, see atomic::Env.

Methods

impl<A, IO, FD, L, V, EX, WD, N, ERR> Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    N: Hash + Eq, 

pub fn with_config(cfg: EnvConfig<A, IO, FD, L, V, EX, WD, N, ERR>) -> Self where
    V: ExportedVariableEnvironment,
    V::VarName: From<String>,
    V::Var: Borrow<String> + From<String>, 

Creates an environment using the provided configuration of subcomponents.

See EnvConfig for the kinds of overrides possible. DefaultEnvConfig comes with provided implementations to get you up and running.

General recommendations:

• The result of evaluating a shell word will often be copied and reused in many different places. It's strongly recommened that Rc or Arc wrappers (e.g. Rc<String>) be used to minimize having to reallocate and copy the same data.
• Whatever type represents a shell function body needs to be cloned to get around borrow restrictions and potential recursive executions and (re-)definitions. Since this type is probably an AST (which may be arbitrarily large), Rc and Arc are your friends.

Trait Implementations

impl<A, IO, FD, L, V, EX, WD, N, ERR> ArgumentsEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    A: ArgumentsEnvironment,
    A::Arg: Clone,
    N: Hash + Eq, 

type Arg = A::Arg

The type of arguments this environment holds.

fn name(&self) -> &Self::Arg

Get the name of the shell.

fn arg(&self, idx: usize) -> Option<&Self::Arg>

Get an argument at any index. Arguments are 1-indexed since the shell variable $0 refers to the shell's name. Thus the first real argument starts at index 1.

fn args_len(&self) -> usize

Get the number of current arguments, NOT including the shell name.

fn args(&self) -> Cow<[Self::Arg]>

Get all current arguments as a possibly owned slice.

impl<A, IO, FD, L, V, EX, WD, N, ERR> SetArgumentsEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    A: SetArgumentsEnvironment,
    N: Hash + Eq, 

type Args = A::Args

A collection of arguments to set.

fn set_args(&mut self, new_args: Self::Args) -> Self::Args

Changes the environment's arguments to new_args and returns the old arguments.

impl<A, IO, FD, L, V, EX, WD, N, ERR> ShiftArgumentsEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    A: ShiftArgumentsEnvironment,
    N: Hash + Eq, 

fn shift_args(&mut self, amt: usize)

Shift parameters such that the positional parameter n will hold the value of the positional parameter n + amt.

impl<A, IO, FD, L, V, EX, WD, N, ERR> AsyncIoEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    IO: AsyncIoEnvironment,
    N: Hash + Eq, 

type Read = IO::Read

An async/futures-aware Read adapter around a FileDesc.

type WriteAll = IO::WriteAll

An future that represents writing data into a FileDesc.

fn read_async(&mut self, fd: FileDesc) -> Self::Read

Creates a futures-aware adapter to read data from a FileDesc asynchronously.

fn write_all(&mut self, fd: FileDesc, data: Vec<u8>) -> Self::WriteAll

Creates a future for writing data into a FileDesc.

fn write_all_best_effort(&mut self, fd: FileDesc, data: Vec<u8>)

Asynchronously write the contents of data to a FileDesc in the background on a best effort basis (e.g. the implementation can give up due to any (appropriately) unforceen errors like broken pipes).

impl<A, IO, FD, L, V, EX, WD, N, ERR> WorkingDirectoryEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    N: Hash + Eq,
    WD: WorkingDirectoryEnvironment, 

fn path_relative_to_working_dir<'a>(&self, path: Cow<'a, Path>) -> Cow<'a, Path>

Converts the specified path to one relative to the environment's working directory.

fn current_working_dir(&self) -> &Path

Retrieves the current working directory of this environment.

impl<A, IO, FD, L, V, EX, WD, N, ERR> ChangeWorkingDirectoryEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    N: Hash + Eq,
    WD: ChangeWorkingDirectoryEnvironment, 

fn change_working_dir<'a>(&mut self, path: Cow<'a, Path>) -> IoResult<()>

Changes the environment's current working directory to the following path.

impl<A, IO, FD, L, V, EX, WD, N, ERR> ExecutableEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    V: UnsetVariableEnvironment,
    N: Hash + Eq,
    EX: ExecutableEnvironment, 

type Future = EX::Future

A future which will resolve to the executable's exit status.

fn spawn_executable(
    &mut self,
    data: ExecutableData
) -> Result<Self::Future, CommandError>

Attempt to spawn the executable command.

impl<A, IO, FD, L, V, EX, WD, N, ERR> FileDescEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    FD: FileDescEnvironment,
    N: Hash + Eq, 

type FileHandle = FD::FileHandle

A file handle (or wrapper) to associate with shell file descriptors.

fn file_desc(&self, fd: Fd) -> Option<(&Self::FileHandle, Permissions)>

Get the permissions and a handle associated with an opened file descriptor.

fn set_file_desc(&mut self, fd: Fd, fdes: Self::FileHandle, perms: Permissions)

Associate a file descriptor with a given handle and permissions.

fn close_file_desc(&mut self, fd: Fd)

Treat the specified file descriptor as closed for the current environment.

impl<A, IO, FD, L, V, EX, WD, N, ERR> FunctionEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    N: Hash + Eq + Clone, 

type FnName = N

The name to be associated with a function.

type Fn = Rc<dyn SpawnBoxed<Self, Error = ERR>>

The type of the function.

fn function(&self, name: &Self::FnName) -> Option<&Self::Fn>

Get a particularly named function if it was registered.

fn set_function(&mut self, name: Self::FnName, func: Self::Fn)

Register a shell function with a given name.

fn has_function(&self, name: &Self::FnName) -> bool

Check if a particularly named function was registered.

impl<A, IO, FD, L, V, EX, WD, N, ERR> UnsetFunctionEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    N: Hash + Eq + Clone, 

fn unset_function(&mut self, name: &Self::FnName)

Removes the definition of a function if it was registered.

impl<A, IO, FD, L, V, EX, WD, N, ERR> LastStatusEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    L: LastStatusEnvironment,
    N: Hash + Eq, 

fn last_status(&self) -> ExitStatus

Get the exit status of the previous command.

fn set_last_status(&mut self, status: ExitStatus)

Set the exit status of the previously run command.

impl<A, IO, FD, L, V, EX, WD, N, ERR> VariableEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    V: VariableEnvironment,
    N: Hash + Eq, 

type VarName = V::VarName

The type of the name this environment associates for a variable.

type Var = V::Var

The type of variables this environment holds.

fn var<Q: ?Sized>(&self, name: &Q) -> Option<&Self::Var> where
    Self::VarName: Borrow<Q>,
    Q: Hash + Eq, 

Get the value of some variable. The values of both shell-only and environment variables will be looked up and returned.

fn set_var(&mut self, name: Self::VarName, val: Self::Var)

Set the value of some variable, maintaining its status as an environment variable if previously set as such.

fn env_vars(&self) -> Cow<[(&Self::VarName, &Self::Var)]>

Unset the value of some variable (including environment variables). Get all current pairs of environment variables and their values.

impl<A, IO, FD, L, V, EX, WD, N, ERR> ExportedVariableEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    V: ExportedVariableEnvironment,
    N: Hash + Eq, 

fn exported_var(&self, name: &Self::VarName) -> Option<(&Self::Var, bool)>

Get the value of some variable and whether it is exported.

fn set_exported_var(
    &mut self,
    name: Self::VarName,
    val: Self::Var,
    exported: bool
)

Set the value of some variable, and set it's exported status as specified.

impl<A, IO, FD, L, V, EX, WD, N, ERR> UnsetVariableEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    V: UnsetVariableEnvironment,
    N: Hash + Eq, 

fn unset_var<Q: ?Sized>(&mut self, name: &Q) where
    Self::VarName: Borrow<Q>,
    Q: Hash + Eq, 

Unset the value of some variable (including environment variables).

impl<A, IO, FD, L, V, EX, WD, N, ERR> IsInteractiveEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    N: Hash + Eq, 

fn is_interactive(&self) -> bool

Indicates if running in interactive mode.

impl<A, IO, FD, L, V, EX, WD, N, ERR> ReportErrorEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    A: ArgumentsEnvironment,
    A::Arg: Display,
    FD: FileDescEnvironment,
    FD::FileHandle: Borrow<FileDesc>,
    N: Hash + Eq, 

fn report_error(&self, err: &dyn Error)

Reports any Error as appropriate, e.g. print to stderr.

impl<A, IO, FD, L, V, EX, WD, N, ERR> SubEnvironment for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    A: SubEnvironment,
    FD: SubEnvironment,
    L: SubEnvironment,
    V: SubEnvironment,
    N: Hash + Eq,
    IO: SubEnvironment,
    EX: SubEnvironment,
    WD: SubEnvironment, 

fn sub_env(&self) -> Self

Create a new sub-environment, which starts out idential to its parent, but any changes on the new environment will not be reflected on the parent.

impl<A, IO, FD, L, V, EX, WD, N, ERR> Clone for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    A: Clone,
    FD: Clone,
    L: Clone,
    V: Clone,
    N: Hash + Eq,
    IO: Clone,
    EX: Clone,
    WD: Clone, 

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<A, IO, FD, L, V, EX, WD, N, ERR> From<EnvConfig<A, IO, FD, L, V, EX, WD, N, ERR>> for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    N: Hash + Eq,
    V: ExportedVariableEnvironment,
    V::VarName: From<String>,
    V::Var: Borrow<String> + From<String>, 

fn from(cfg: EnvConfig<A, IO, FD, L, V, EX, WD, N, ERR>) -> Self

Performs the conversion.

impl<A, IO, FD, L, V, EX, WD, N, ERR> Debug for Env<A, IO, FD, L, V, EX, WD, N, ERR> where
    A: Debug,
    FD: Debug,
    L: Debug,
    V: Debug,
    N: Hash + Eq + Ord + Debug,
    IO: Debug,
    EX: Debug,
    WD: Debug, 

fn fmt(&self, fmt: &mut Formatter) -> Result

Formats the value using the given formatter.