Struct illicit::Layer

pub struct Layer { /* fields omitted */ }

A container for the local environment, usually used to represent a pending addition to it.

The environment is type-indexed, and access is provided through read-only references. Call Layer::offer to include new values in the environment for called functions and get or expect to retrieve references to the offered values.

Aside: one interesting implication of the above is the ability to define "private scoped global values" which are private to functions which are nonetheless propagating the values with their control flow. This can be useful for runtimes to offer themselves execution-local values in functions which are invoked by external code. It can also be severely abused, like any implicit state, and should be used with caution.

Examples

Code always sees the contents of the "bottom-most" Layer:

illicit::Layer::new().offer(String::new()).offer(5u16).enter(|| {
    assert!(illicit::expect::<String>().is_empty());
    assert_eq!(*illicit::expect::<u16>(), 5);

    illicit::Layer::new().offer(10u16).enter(|| {
        assert!(illicit::expect::<String>().is_empty());
        assert_eq!(*illicit::expect::<u16>(), 10);
    });

    assert!(illicit::expect::<String>().is_empty());
    assert_eq!(*illicit::expect::<u16>(), 5);
});

Implementations

impl Layer

pub fn new() -> Self

Construct a new layer which defaults to the contents of the current one. Call Layer::offer to add values to the new layer before calling Layer::enter to run a closure with access to the new and old values.

pub fn offer<E>(self, v: E) -> Self where
    E: Debug + 'static, 

Adds the new item and returns the modified layer.

The offered type must implement Debug to allow get's errors to display the contents of the illicit environment. It must also satisfy the 'static lifetime because get is unable to express any lifetime constraints at its callsite.

pub fn enter<R>(self, child_fn: impl FnOnce() -> R) -> R

Call child_fn with this layer as the local environment.

Trait Implementations

impl Clone for Layer

fn clone(&self) -> Layer

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Layer

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

Formats the value using the given formatter.

impl Default for Layer

fn default() -> Self

Returns the "default value" for a type.

impl From<Snapshot> for Layer

fn from(snapshot: Snapshot) -> Self

Performs the conversion.

impl RefUnwindSafe for Layer

impl UnwindSafe for Layer