Struct viro::Viro

pub struct Viro { /* private fields */ }

An environment.

This uses a hard-coded set of environment variables to determine whether a variable should be a “scalar”, having a singular value, or a “vector”, having multiple values. It also checks what separators are used for particular variables, and excludes certain variables which are not intended to be passed around.

For example, PATH is a vector which separates its values using semicolons on Windows and colons on other platforms; and the SHELL variable is one that should not be included.

The currently known variables are:

Key	Behavior
_	Excluded
GOPATH	Separated by colons
GOPATH	Separated by colons
GPG_TTY	Excluded
HOME	Excluded
LD_LIBRARY_PATH	Separated by colons; may also be separated by semicolons
LD_PRELOAD	Separated by colons; may also be separated by spaces
LS_COLORS	Terminated by colons
MANPATH	Separated by colons
NOTIFY_SOCKET	Excluded
PATH	Separated by semicolons on windows, colons on other platforms
PERL5LIB	Separated by colons
PERLLIB	Separated by colons
PWD	Excluded
PYTHONPATH	Separated by colons
SHELL	Excluded
SHLVL	Excluded
USER	Excluded

Implementations

impl Viro

pub fn new() -> Viro

Makes an empty environment.

Examples

use viro::Viro;

let mut env = Viro::new();

let mut ser = env.write_bytes();
assert_eq!(ser, &[]);

pub fn insert<S: AsRef<[u8]> + Into<Vec<u8>>, T: AsRef<[u8]> + Into<Vec<u8>>>( &mut self, key: S, val: T )

Dumps a key-value pair into the environment.

This does not perform any validation on the keys or values, accepting all possible byte sequences. If the key contains a \x3D byte (equals sign), or the key or value contain a \0 (NUL) byte, the resulting serialization will be incorrect.

Examples

use viro::Viro;

let mut env = Viro::new();
env.insert("PATH", "/bin:/sbin");
env.insert("PATH", "/sbin:/bin:/usr/bin");
env.insert("SHELL", "/bin/bash");

let ser = env.write_bytes();
assert_eq!(ser, &b"PATH=/bin:/sbin:/usr/bin\0"[..]);

pub fn remove<S: AsRef<[u8]>>(&mut self, key: S)

Removes a key-value pair from the environment.

This completely removes the key from the serialized format.

Examples

use viro::Viro;

let mut env = Viro::new();
env.insert("PATH", "/bin:/sbin");
env.remove("PATH");
env.insert("PATH", "/sbin:/bin:/usr/bin");

let ser = env.write_bytes();
assert_eq!(ser, &b"PATH=/sbin:/bin:/usr/bin\0"[..]);

pub fn process<S: AsRef<[u8]>>(&mut self, item: S)

Processes a serialized item.

This is equivalent to insert if the item contains an equals sign, and remove if the item does not contain an equal sign.

Like insert, this does not check for NUL bytes in the item, and including them will result in the serialization being incorrect.

Examples

use viro::Viro;

let mut env = Viro::new();
env.process("PATH=/bin:/sbin");
env.process("PATH");
env.process("PATH=/sbin:/bin:/usr/bin");

let ser = env.write_bytes();
assert_eq!(ser, &b"PATH=/sbin:/bin:/usr/bin\0"[..]);

pub fn read<R: ?Sized + SyncBufRead>(&mut self, reader: &mut R) -> Result<()>

Available on crate feature sync only.

Reads an environment from a reader.

The interprets the input as a NUL-delimited list. If an item contains an equal sign, it is treated as a key-value pair to be included in the environment. If it does not, it is treated as a variable to be removed.

Examples

use viro::Viro;

let mut env = Viro::new();
let mut data = &b"PATH=/bin:/sbin\0PATH\0PATH=/sbin:/bin:/usr/bin"[..];
env.read(&mut data)?;

let ser = env.write_bytes();
assert_eq!(ser, &b"PATH=/sbin:/bin:/usr/bin\0"[..]);

pub async fn read_async<R: ?Sized + AsyncBufRead>( &mut self, reader: Pin<&mut R> ) -> Result<()>

Available on crate feature async only.

Async version of read.

Examples

use std::pin::Pin;
use viro::Viro;

let mut env = Viro::new();
let mut data = &b"PATH=/bin:/sbin\0PATH\0PATH=/sbin:/bin:/usr/bin"[..];
env.read_async(Pin::new(&mut data)).await?;

let ser = env.write_bytes();
assert_eq!(ser, &b"PATH=/sbin:/bin:/usr/bin\0"[..]);

pub fn read_bytes(&mut self, bytes: &[u8])

Reads the environment from a byte slice.

Examples

use viro::Viro;

let mut env = Viro::new();
let mut data = &b"PATH=/bin:/sbin\0PATH\0PATH=/sbin:/bin:/usr/bin"[..];
env.read_bytes(data);

let ser = env.write_bytes();
assert_eq!(ser, &b"PATH=/sbin:/bin:/usr/bin\0"[..]);

pub fn read_stdin(&mut self) -> Result<()>

Available on crate feature sync-stdio only.

Reads the environment from stdin.

Examples

use viro::Viro;

let mut env = Viro::new();
env.read_stdin()?;

pub async fn read_stdin_async(&mut self) -> Result<()>

Available on crate feature async-stdio only.

Async version of read_stdin.

Examples

use viro::Viro;

let mut env = Viro::new();
env.read_stdin_async().await?;

pub fn serialized(&mut self) -> ViroIter<'_>

Creates an iterator over the serialized byte-slices of an environment.

This returns an iterator to avoid allocating any new memory; simply concatenate the values returned by this iterator to get the full serialized version. Sorts the variables in byte order before serializing.

The format is exactly the same as the one for read, although every item in the resulting NUL-delimited list will contain an equals sign; variables that would be removed are simply omitted.

The actual separation of the output may change in the future, although this is unlikely. You should only rely on the concatenation of the iterands, and not their values.

Examples

use viro::Viro;

let mut env = Viro::new();
env.insert("PATH", "/bin:/sbin:/usr/bin");
env.insert("SHELL", "/bin/bash");
env.insert("LD_LIBRARY_PATH", "/lib");

let mut ser = Vec::new();
for slice in env.serialized() {
    ser.extend_from_slice(slice);
}
assert_eq!(ser, &b"LD_LIBRARY_PATH=/lib\0PATH=/bin:/sbin:/usr/bin\0"[..]);

pub fn write<W: ?Sized + SyncWrite>(&mut self, writer: &mut W) -> Result<()>

Available on crate feature sync only.

Writes the environment to a writer and flushes it.

Examples

use viro::Viro;

let mut env = Viro::new();
env.insert("PATH", "/bin:/sbin:/usr/bin");
env.insert("SHELL", "/bin/bash");

let mut ser = Vec::new();
env.write(&mut ser)?;
assert_eq!(ser, &b"PATH=/bin:/sbin:/usr/bin\0"[..]);

pub async fn write_async<'w, W: ?Sized + AsyncWrite>( &'w mut self, writer: Pin<&'w mut W> ) -> Result<()>

Available on crate feature async only.

Async version of write.

Examples

use std::pin::Pin;
use viro::Viro;

let mut env = Viro::new();
env.insert("PATH", "/bin:/sbin:/usr/bin");
env.insert("SHELL", "/bin/bash");

let mut ser = Vec::new();
env.write_async(Pin::new(&mut ser)).await?;
assert_eq!(ser, &b"PATH=/bin:/sbin:/usr/bin\0"[..]);

pub fn write_bytes(&mut self) -> Vec<u8>

Writes the environment to a byte vector.

Examples

use viro::Viro;

let mut env = Viro::new();
env.insert("PATH", "/bin:/sbin:/usr/bin");
env.insert("SHELL", "/bin/bash");

let mut ser = env.write_bytes();
assert_eq!(ser, &b"PATH=/bin:/sbin:/usr/bin\0"[..]);

pub fn write_stdout(&mut self) -> Result<()>

Available on crate feature sync-stdio only.

Writes the environment out to stdout.

Examples

use viro::Viro;

let mut env = Viro::new();
env.insert("PATH", "/bin:/sbin:/usr/bin");
env.insert("SHELL", "/bin/bash");

env.write_stdout()?;

pub async fn write_stdout_async(&mut self) -> Result<()>

Available on crate feature async-stdio only.

Async version of write_stdout.

Examples

use viro::Viro;

let mut env = Viro::new();
env.insert("PATH", "/bin:/sbin:/usr/bin");
env.insert("SHELL", "/bin/bash");

env.write_stdout_async().await?;

pub fn write_stderr(&mut self) -> Result<()>

Available on crate feature sync-stdio only.

Writes the environment out to stderr.

Examples

use viro::Viro;

let mut env = Viro::new();
env.insert("PATH", "/bin:/sbin:/usr/bin");
env.insert("SHELL", "/bin/bash");

env.write_stderr()?;

pub async fn write_stderr_async(&mut self) -> Result<()>

Available on crate feature async-stdio only.

Async version of write_stderr.

Examples

use viro::Viro;

let mut env = Viro::new();
env.insert("PATH", "/bin:/sbin:/usr/bin");
env.insert("SHELL", "/bin/bash");

env.write_stderr_async().await?;

Trait Implementations

impl Clone for Viro

fn clone(&self) -> Viro

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Viro

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

Formats the value using the given formatter.

impl Default for Viro

fn default() -> Viro

Returns the “default value” for a type.