elly_host/

io.rs

//! Building `IO`, the root capability a runner hands a program, and running a
//! program's `__main` against it.
//!
//! Two modules, each written in Elly (`io.ly`, `proc.ly`) over host callbacks
//! supplied through its **frame**. That is the frame mechanism doing what it was
//! built for, and it is the only sound route: a `ModuleData` is env-free so one
//! compile can serve many instantiations, so an `Expr` holds no `Value` and code
//! cannot carry a callback directly.
//!
//! Submodules fall out of the same shape. `IO.Proc` is built first and its
//! instance handed to `IO`'s frame, where `Proc = proc_impl` is an ordinary
//! forwarding item — the shape `Foo = import "spec"` already compiles to.

use std::rc::Rc;

use elly_core::{
    apply_with, compile_module_framed, eval_main, instantiate, Ctx, Raised, Text, Value,
};

use crate::{Stream, Sys};

const IO_SRC: &str = include_str!("io.ly");
const PROC_SRC: &str = include_str!("proc.ly");

/// The built capability, plus the one thing about it a runner has to recognize.
pub struct Io {
    /// The `IO` module instance — what `__main` is applied to, and the whole of
    /// what the program is authorized to do.
    pub value: Value,
    /// The iota `IO.Proc.return` raises with. [`Io::run`] compares an uncaught
    /// raise against it to tell "the program asked to exit with a status" from
    /// "the program failed"; nothing else can mint this value.
    pub returned: Value,
}

/// How running a program's `__main` against `IO` ended.
pub enum Run {
    /// The module has no `__main`: it is a library rather than a program.
    Library,
    /// `__main` returned this value. A runner ignores it — printing a result is
    /// REPL behaviour — except to notice an entry still wanting arguments.
    Returned(Value),
    /// `IO.Proc.return` asked for this exit status.
    Exit(u8),
    /// A raise reached the top.
    Raised(Raised),
}

/// Build `IO` over `sys` for a program invoked with `args` (the arguments after
/// the script).
///
/// Panics only on a bug in the sources compiled in here — a mis-declared frame
/// slot or a syntax error in `io.ly` / `proc.ly` — which is a build-time mistake
/// in this crate, not anything a user's program can cause.
pub fn io(sys: Rc<dyn Sys>, args: &[String], ctx: &Ctx) -> Io {
    let proc = instantiate_host(
        PROC_SRC,
        &[
            ("args_impl", Value::list(args.iter().map(str_value))),
            ("env_impl", env_value(&*sys)),
            ("exit_impl", exit_fn(sys.clone())),
        ],
        ctx,
    );
    let returned =
        apply_with(&proc, symbol("returned"), ctx).expect("`proc.ly` declares `returned`");
    let value = instantiate_host(
        IO_SRC,
        &[
            ("proc_impl", proc),
            ("print_impl", writer(&sys, "print", Stream::Out, true)),
            ("write_impl", writer(&sys, "write", Stream::Out, false)),
            ("error_impl", writer(&sys, "error", Stream::Err, true)),
        ],
        ctx,
    );
    Io { value, returned }
}

impl Io {
    /// Run `instance`'s `__main`: evaluate the body in the module's own
    /// environment, apply the result to `IO`, and say how it ended.
    pub fn run(&self, instance: &Value, ctx: &Ctx) -> Run {
        let entry = match eval_main(instance, ctx) {
            Ok(Some(entry)) => entry,
            Ok(None) => return Run::Library,
            // The body itself raised, before the capability was ever applied.
            Err(r) => return self.raised(r),
        };
        self.finish(apply_with(&entry, self.value.clone(), ctx))
    }

    /// Say how a computation that was given `IO` ended. [`run`](Self::run) uses
    /// it for `__main`; a host that hands `IO` to something else, such as the
    /// playground's bare expression, uses it directly.
    pub fn finish(&self, result: Result<Value, Raised>) -> Run {
        match result {
            Ok(value) => Run::Returned(value),
            Err(r) => self.raised(r),
        }
    }

    /// Either `IO.Proc.return`'s unwind — the program asking for an exit
    /// status — or a genuine failure.
    fn raised(&self, r: Raised) -> Run {
        match self.requested_exit(r.value()) {
            Some(code) => Run::Exit(code),
            None => Run::Raised(r),
        }
    }

    /// The status `IO.Proc.return n` asked for, if that is what this raise is: a
    /// two-element list led by the iota only `IO.Proc` can mint. An ordinary
    /// raise cannot be mistaken for one, whatever shape it has, because it cannot
    /// hold that value.
    ///
    /// A status outside a byte is taken modulo 256, as a shell reports one
    /// anyway.
    fn requested_exit(&self, payload: &Value) -> Option<u8> {
        let mut items = payload.list_items()?;
        if items.len() != 2 {
            return None;
        }
        if items.next()? != &self.returned {
            return None;
        }
        match items.next()? {
            Value::I64(code) => Some(*code as u8),
            _ => None,
        }
    }
}

/// Compile a host module's source against the named `slots` and instantiate it
/// with their values — the two halves of one declaration, kept next to each other
/// so a slot cannot drift out of the order the frame is filled in.
fn instantiate_host(src: &str, slots: &[(&str, Value)], ctx: &Ctx) -> Value {
    let names: Vec<Text> = slots.iter().map(|(n, _)| Text::from(*n)).collect();
    let values: Vec<Value> = slots.iter().map(|(_, v)| v.clone()).collect();
    let data = compile_module_framed(src, &names).expect("a host module compiles");
    instantiate(data, &values, ctx).expect("a host module's frame is exactly its slots")
}

/// A `Str → []` callback that writes its argument to `stream`, optionally
/// followed by a newline. This is the whole of `IO`'s output surface today.
///
/// It answers unit (the empty list) rather than the string, so a caller reads
/// nothing back out of a write, and it raises `.io_error` rather than panicking
/// on a closed pipe — a write failure is the program's to see, on the same
/// channel every other host failure uses.
fn writer(sys: &Rc<dyn Sys>, name: &'static str, stream: Stream, newline: bool) -> Value {
    let sys = sys.clone();
    Value::host_fn(name, 1, move |args, _ctx| {
        let Value::Str(s) = &args[0] else {
            return Err(raise("not_a_str"));
        };
        let written = if newline {
            sys.write(stream, &format!("{s}\n"))
        } else {
            sys.write(stream, s)
        };
        written.map_err(|_| raise("io_error"))?;
        Ok(Value::list([]))
    })
}

/// `Int → ⊥`: exit the process immediately, with no unwinding and nothing running
/// after it — `std::process::exit`, with no surprises. A status outside the range
/// the platform can carry is the caller's mistake, so it raises rather than being
/// silently truncated.
fn exit_fn(sys: Rc<dyn Sys>) -> Value {
    Value::host_fn("exit", 1, move |args, _ctx| {
        let Value::I64(code) = args[0] else {
            return Err(raise("not_an_int"));
        };
        let Ok(code) = i32::try_from(code) else {
            return Err(raise("bad_exit_code"));
        };
        sys.exit(code)
    })
}

/// The environment as a map from name to value, read once at startup.
fn env_value(sys: &dyn Sys) -> Value {
    Value::map(
        sys.vars()
            .into_iter()
            .map(|(k, v)| (str_value(k), str_value(v))),
    )
}

fn str_value(s: impl AsRef<str>) -> Value {
    Value::Str(Text::from(s.as_ref()))
}

fn symbol(s: &str) -> Value {
    Value::Symbol(Text::from(s))
}

/// One of the host-failure tags, raised on the single error channel everything
/// else uses (see the *error handling* section of `docs/elly-spec.md`).
fn raise(tag: &'static str) -> Raised {
    Raised::Error(Value::Symbol(Text::from_static(tag)))
}