Struct Environment

pub struct Environment<'i, 'o, 'c> { /* private fields */ }

The execution environment for Knight programs.

To aid in embedding Knight in other systems, the Environment provides complete control over the stdin, stdout, and output of the “system” (`), in addition to keeping track of all relevant variables. Because of this, the environment must always be passed when calling Value::run.

This is in contrast with most other Knight implementations, which usually have a singular, global “environment”, and

Examples

let mut env = Environment::new();

// Write to stdout.
writeln!(env, "Hello, world!");

// Read from stdin.
let mut str = String::new();
env.read_to_string(&mut str).expect("cant read from stdin!");

// execute command
println!("The stdout of `ls -al` is {}", env.system("ls -al").expect("`ls -al` failed"));

// create a variable
let var = env.get("foobar");
assert_eq!(var, env.get("foobar")); // both variables are the same.

Implementations

impl<'i, 'o, 'c> Environment<'i, 'o, 'c>

pub fn new() -> Self

Creates an empty Environment.

Examples

let env = Environment::new();

// ...do stuff with `env`.

pub fn builder() -> Builder<'i, 'o, 'c>

Creates a new Builder.

This is simply a helper function, and is provided so that you don’t have to import Builder.

Examples

let env = Environment::builder().disable_system().build();

// ... do stuff with `env`.

pub fn get<N: AsRef<str> + ToString + ?Sized>(&mut self, name: &N) -> Variable

Retrieves the variable with the given name.

This method will always succeed; if this is the first time that name has been seen by self, a new (unassigned ) variable will be created.

Examples

let mut env = Environment::new();
let var = env.get("plato");

assert_eq!(var, env.get("plato"));

pub fn system(&mut self, cmd: &str) -> Result<Text>

Executes cmd as a system command, returning the stdout of the child process.

This will internally call the value that was set for Builder::system. See that function for more details on, eg, the default value.

Examples

let mut env = Environment::new();

assert_eq!(env.system("echo 'hello, knight!'").unwrap().as_str(), "hello, knight!\n");

pub fn run_str<S: AsRef<str>>(&mut self, input: S) -> Result<Value>

Runs the given string as Knight code, returning the result of its execution.

pub fn run<I>(&mut self, input: I) -> Result<Value>

where I: IntoIterator<Item = char>,

Parses a Value from the given iterator and then runs the value.

Trait Implementations

impl BufRead for Environment<'_, '_, '_>

fn fill_buf(&mut self) -> Result<&[u8]>

Returns the contents of the internal buffer, filling it with more data, via Read methods, if empty.

fn consume(&mut self, amnt: usize)

Marks the given amount of additional bytes from the internal buffer as having been read. Subsequent calls to read only return bytes that have not been marked as read.

fn read_line(&mut self, buf: &mut String) -> Result<usize>

Reads all bytes until a newline (the 0xA byte) is reached, and append them to the provided String buffer.

fn has_data_left(&mut self) -> Result<bool, Error>

🔬This is a nightly-only experimental API. (buf_read_has_data_left)

Checks if there is any data left to be read.

fn read_until(&mut self, byte: u8, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes into buf until the delimiter byte or EOF is reached.

fn skip_until(&mut self, byte: u8) -> Result<usize, Error>

Skips all bytes until the delimiter byte or EOF is reached.

fn split(self, byte: u8) -> Split<Self>

where Self: Sized,

Returns an iterator over the contents of this reader split on the byte byte.

fn lines(self) -> Lines<Self>

where Self: Sized,

Returns an iterator over the lines of this reader.

impl Debug for Environment<'_, '_, '_>

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

Formats the value using the given formatter.

impl Default for Environment<'_, '_, '_>

fn default() -> Self

Returns the “default value” for a type.

impl Read for Environment<'_, '_, '_>

fn read(&mut self, data: &mut [u8]) -> Result<usize>

Read bytes into data from self’s stdin.

The stdin can be customized at creation via Builder::stdin.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl Write for Environment<'_, '_, '_>

fn write(&mut self, data: &[u8]) -> Result<usize>

Writes data’s bytes into self’s stdout.

The stdin can be customized at creation via Builder::stdin.

fn flush(&mut self) -> Result<()>

Flushes this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.