nanvm_lib/vm/lambda/

mod.rs

//! The three continuation types of `fjs/edag/README.md`'s Chains section,
//! one per combination of its two bits — a receiver is live (P), a
//! short-circuit region is open (O) — that is not a node boundary. A
//! chain is opened by a node's entry point on [`Any`] (`dot`, `option_dot`,
//! `option_call` in `vm/any`), continued by one method per step the README
//! allows in that state, and closed by `end` or `end_call`, which alone
//! answer the chain's `Result`. A step the README does not allow is a
//! method that does not exist, so a spelling that disagrees with the
//! README does not compile.
//!
//! None of the three is `Clone`, and every method consumes `self`: a
//! continuation "cannot be lifted out as a shared node", so a chain is used
//! once, and `#[must_use]` makes a chain used zero times a warning. What a
//! terminal answers is an ordinary `Result<Any<A>, Any<A>>`, shareable as
//! any value is — neither bit is ever the result of an `exp`.
//!
//! A step's order is *guard, thunk, operation*: a guarded step looks at the
//! current value for nullishness first and skips its thunk on it; every
//! callable validation follows argument evaluation, and a computed key
//! precedes its property read. A member call resolves its property and
//! runtime callee before forcing arguments, retaining lookup failures;
//! resolving a noncallable value does not validate it yet.
//!
//! A property step holds its receiver and key, [`Member`], and the read
//! waits for the exit: `end` reads, and a call exit resolves the callee —
//! an object's own property or an array's element first, then the
//! function the runtime value's `dot` answers for the receiver, then the
//! receiver type's built-in member function ([`method`](method::method))
//! for a name without a body, then the `TypeError` for calling `undefined`. A call step on a member
//! takes the runtime value for that, `&runtime`, the parameter every
//! compiled module receives (`fjs/js/runtime/README.md`, "How NaNVM finds
//! it"); a step on a plain value needs none. No user function reads
//! `this`, so `Function::call` takes no receiver and never will: the
//! receiver is consumed by the built-in and handed to nothing. Which
//! built-ins the table answers is `nanvm/lib/todo/member-functions.md`.

use crate::vm::{Any, IVm};

pub(crate) mod member;
mod method;
mod number;
mod string;

/// The shared runtime-only pairs and the completeness table `method`'s test
/// checks it against, generated by `fjs/nanvm/methods` — a `#[path]`, since a
/// `gen.` name is not a Rust identifier.
#[path = "gen.methods.rs"]
mod methods_table;

pub(crate) use member::Member;

/// What a chain's live state can do, whatever it holds: a bare value, the
/// state after a call step or a `?.()` node, or a [`Member`], the receiver
/// and key of a property step whose read waits for the exit.
pub(crate) trait Live<A: IVm>: Sized {
    /// The chain's current value: the value itself, or the property read.
    fn value(self) -> Any<A>;
    /// The guard of a `?.()` step: whether what the call would call is
    /// nullish, or the throw of deciding, a member's body deciding for its
    /// receiver, which the runtime value's `dot` answers.
    fn is_nullish(&self, runtime: &Any<A>) -> Result<bool, Any<A>>;
    /// Resolve before arguments, retaining lookup failures while postponing
    /// callable validation. Bare values have no member lookup to perform.
    fn resolve(&self, runtime: &Any<A>) -> Result<(), Any<A>>;
    /// The call, its arguments evaluated: `Any::call` of a value, and a
    /// member's resolution — the receiver's own property, the function
    /// the runtime value's `dot` answers, the native for a name without a
    /// body, the `TypeError`.
    fn call(self, runtime: &Any<A>, args: Any<A>) -> Result<Any<A>, Any<A>>;
}

impl<A: IVm> Live<A> for Any<A> {
    fn value(self) -> Any<A> {
        self
    }
    fn is_nullish(&self, _runtime: &Any<A>) -> Result<bool, Any<A>> {
        Ok(Any::is_nullish(self))
    }
    fn resolve(&self, _runtime: &Any<A>) -> Result<(), Any<A>> {
        Ok(())
    }
    fn call(self, _runtime: &Any<A>, args: Any<A>) -> Result<Any<A>, Any<A>> {
        Any::call(self, args)
    }
}

impl<A: IVm> Live<A> for Member<A> {
    fn value(self) -> Any<A> {
        self.read()
    }
    fn is_nullish(&self, runtime: &Any<A>) -> Result<bool, Any<A>> {
        Member::is_nullish(self, runtime)
    }
    fn resolve(&self, runtime: &Any<A>) -> Result<(), Any<A>> {
        self.is_nullish(runtime).map(|_| ())
    }
    fn call(self, runtime: &Any<A>, args: Any<A>) -> Result<Any<A>, Any<A>> {
        Member::call(self, runtime, args)
    }
}

/// The state of a chain inside an open region: live, skipped by a guard, or
/// thrown. Skipped and thrown pass through every step; `end` tells them
/// apart.
pub(crate) enum Region<A: IVm, T: Live<A>> {
    Live(T),
    Skipped,
    Thrown(Any<A>),
}

impl<A: IVm, T: Live<A>> From<Result<T, Any<A>>> for Region<A, T> {
    fn from(r: Result<T, Any<A>>) -> Self {
        match r {
            Ok(v) => Region::Live(v),
            Err(e) => Region::Thrown(e),
        }
    }
}

impl<A: IVm, T: Live<A>> Region<A, T> {
    /// The region closed: a skipped chain is `undefined`, the value a
    /// short-circuit answers.
    fn end(self) -> Result<Any<A>, Any<A>> {
        match self {
            Region::Live(v) => Ok(v.value()),
            Region::Skipped => Ok(Any::undefined()),
            Region::Thrown(e) => Err(e),
        }
    }
    /// An unguarded step: `op` over a live state, nothing otherwise.
    fn step<U: Live<A>>(self, op: impl FnOnce(T) -> Result<U, Any<A>>) -> Region<A, U> {
        match self {
            Region::Live(v) => op(v).into(),
            Region::Skipped => Region::Skipped,
            Region::Thrown(e) => Region::Thrown(e),
        }
    }
    /// `|()`: resolve a member, force the arguments, then call. Callable
    /// validation follows arguments; lookup failure precedes them.
    fn call(
        self,
        runtime: &Any<A>,
        args: impl FnOnce() -> Result<Any<A>, Any<A>>,
    ) -> Region<A, Any<A>> {
        self.step(|v| {
            v.resolve(runtime)
                .and_then(|()| args())
                .and_then(|a| v.call(runtime, a))
        })
    }
    /// `|.`: the key forced, then the step over the current value as the
    /// receiver, whose nullish throw therefore comes second.
    pub(crate) fn dot(self, key: impl FnOnce() -> Result<Any<A>, Any<A>>) -> Region<A, Member<A>> {
        self.step(|v| key().and_then(|k| Member::new(v.value(), k)))
    }
    /// A guard: the region skipped where the live state is nullish, thrown
    /// where deciding throws, and otherwise `step` over it; nothing for a
    /// region already skipped or thrown. A member decides with the runtime
    /// value, whose `dot` may answer a callee for its receiver.
    fn guarded<U: Live<A>>(
        self,
        runtime: &Any<A>,
        step: impl FnOnce(Self) -> Region<A, U>,
    ) -> Region<A, U> {
        match self {
            Region::Live(v) => match v.is_nullish(runtime) {
                Err(e) => Region::Thrown(e),
                Ok(true) => Region::Skipped,
                Ok(false) => step(Region::Live(v)),
            },
            Region::Skipped => Region::Skipped,
            Region::Thrown(e) => Region::Thrown(e),
        }
    }
    /// `|?.()`: a nullish callee skips the rest of the chain, its
    /// arguments untouched; any other is called.
    pub(crate) fn option_call(
        self,
        runtime: &Any<A>,
        args: impl FnOnce() -> Result<Any<A>, Any<A>>,
    ) -> Region<A, Any<A>> {
        // The guard already performed the preargument resolution.
        self.guarded(runtime, |live| {
            live.step(|v| args().and_then(|a| v.call(runtime, a)))
        })
    }
}

impl<A: IVm> Region<A, Any<A>> {
    /// The `?.` node's own step, on a plain value: a nullish receiver skips
    /// the key and the rest of the chain; any other takes the step `|.`
    /// takes. The guard is the value's own nullishness, which asks no
    /// runtime.
    pub(crate) fn option_dot(
        self,
        key: impl FnOnce() -> Result<Any<A>, Any<A>>,
    ) -> Region<A, Member<A>> {
        match self {
            Region::Live(v) if Any::is_nullish(&v) => Region::Skipped,
            live => live.dot(key),
        }
    }
    /// `|()` on a plain value, the state after a call step or a `?.()`
    /// node: `Any::call`, which asks no runtime.
    fn call_value(self, args: impl FnOnce() -> Result<Any<A>, Any<A>>) -> Region<A, Any<A>> {
        self.step(|v| args().and_then(|a| Any::call(v, a)))
    }
    /// `?.()` on a plain value, the node's own step and a `|?.()` step on
    /// the state after a call: a nullish callee skips, any other is called.
    pub(crate) fn option_call_value(
        self,
        args: impl FnOnce() -> Result<Any<A>, Any<A>>,
    ) -> Region<A, Any<A>> {
        match self {
            Region::Live(v) if Any::is_nullish(&v) => Region::Skipped,
            live => live.call_value(args),
        }
    }
}

/// A receiver is live and no region is open: the state after a `.` node,
/// `a.b`. Its steps are `|()` (`end_call`) and `|?.()` (`option_call`);
/// `end` is the bare node, the read with its receiver dropped — the one
/// property read `nanvm-lib` has, `dot(a, key).end()`.
///
/// No region, so no skipped state: the interior is the step's own
/// `Result`, its nullish-receiver throw waiting for a terminal to surface
/// it — `a.b(...c)` on a nullish `a` throws at the access with `c`
/// untouched, which is why `end_call` takes its arguments as a thunk.
#[must_use]
pub struct PropertyLambda<A: IVm>(pub(crate) Result<Member<A>, Any<A>>);

impl<A: IVm> PropertyLambda<A> {
    /// No continuation: `a.b`.
    pub fn end(self) -> Result<Any<A>, Any<A>> {
        self.0.map(Member::read)
    }
    /// `|()`, terminal: `a.b(...args)`, the property called on its
    /// receiver — an own property, or a built-in member function. No
    /// region is open, so this is also what a `|!()` would be — "there is
    /// no bit to clear".
    pub fn end_call(
        self,
        runtime: &Any<A>,
        args: impl FnOnce() -> Result<Any<A>, Any<A>>,
    ) -> Result<Any<A>, Any<A>> {
        // A `Result`-sourced region is never skipped, so `end` is exact.
        Region::from(self.0).call(runtime, args).end()
    }
    /// `|()` of an intrinsic's helper, `slice(s, a, b)`: the member call
    /// that asks no runtime, the own property else the native else the
    /// `TypeError`, since no body defines the name
    /// ([`Member::call_native`]).
    pub fn end_call_native(
        self,
        args: impl FnOnce() -> Result<Any<A>, Any<A>>,
    ) -> Result<Any<A>, Any<A>> {
        self.0.and_then(|m| args().and_then(|a| m.call_native(a)))
    }
    /// `|?.()`: `a.b?.(...args)`, opening a region.
    pub fn option_call(
        self,
        runtime: &Any<A>,
        args: impl FnOnce() -> Result<Any<A>, Any<A>>,
    ) -> OptionLambda<A> {
        OptionLambda(Region::from(self.0).option_call(runtime, args))
    }
}

/// A region is open and no receiver is live: the state after a `?.()` node,
/// `a?.(...b)`, or a `|()` or `|?.()` step inside a region. Its steps are
/// `|()` (`call`) and `|.` (`dot`); no `|?.()`, and no `|!()` — there is no
/// receiver for either to justify.
#[must_use]
pub struct OptionLambda<A: IVm>(pub(crate) Region<A, Any<A>>);

impl<A: IVm> OptionLambda<A> {
    /// No continuation: the region closes, a skipped chain is `undefined`.
    pub fn end(self) -> Result<Any<A>, Any<A>> {
        self.0.end()
    }
    /// `|()`: call the current value, inside the region.
    pub fn call(self, args: impl FnOnce() -> Result<Any<A>, Any<A>>) -> OptionLambda<A> {
        OptionLambda(self.0.call_value(args))
    }
    /// `|.`: a property of the current value, inside the region; the value
    /// becomes the receiver.
    pub fn dot(self, key: impl FnOnce() -> Result<Any<A>, Any<A>>) -> OptionPropertyLambda<A> {
        OptionPropertyLambda(self.0.dot(key))
    }
}

/// Both bits live: the state after a `?.` node, `a?.b`, or a `|.` step
/// inside a region. Every step is legal here: `|()` (`call`), `|.` (`dot`),
/// `|?.()` (`option_call`) and `|!()` (`end_call`).
#[must_use]
pub struct OptionPropertyLambda<A: IVm>(pub(crate) Region<A, Member<A>>);

impl<A: IVm> OptionPropertyLambda<A> {
    /// No continuation: `(a?.b)`, the region closed with nothing after it.
    pub fn end(self) -> Result<Any<A>, Any<A>> {
        self.0.end()
    }
    /// `|()`: `a?.b(...args)`, the property called on its receiver, skipped
    /// with the region.
    pub fn call(
        self,
        runtime: &Any<A>,
        args: impl FnOnce() -> Result<Any<A>, Any<A>>,
    ) -> OptionLambda<A> {
        OptionLambda(self.0.call(runtime, args))
    }
    /// `|.`: `a?.b.c`, skipped with the region.
    pub fn dot(self, key: impl FnOnce() -> Result<Any<A>, Any<A>>) -> OptionPropertyLambda<A> {
        OptionPropertyLambda(self.0.dot(key))
    }
    /// `|?.()`: `a?.b?.(...args)`, its own guard on the callee.
    pub fn option_call(
        self,
        runtime: &Any<A>,
        args: impl FnOnce() -> Result<Any<A>, Any<A>>,
    ) -> OptionLambda<A> {
        OptionLambda(self.0.option_call(runtime, args))
    }
    /// `|!()`, terminal: `(a?.b)(...args)`. The parentheses close the
    /// region first, so a skipped chain is `undefined` here and the call
    /// happens regardless — the arguments are evaluated, then `undefined`
    /// is called and throws. A live chain calls the property on its
    /// receiver; a thrown chain stays thrown, arguments untouched.
    pub fn end_call(
        self,
        runtime: &Any<A>,
        args: impl FnOnce() -> Result<Any<A>, Any<A>>,
    ) -> Result<Any<A>, Any<A>> {
        match self.0 {
            Region::Skipped => args().and_then(|a| Any::undefined().call(a)),
            region => region.call(runtime, args).end(),
        }
    }
}

#[cfg(test)]
mod tests {
    use crate::vm::test::function::{identity, returns, rt};
    use crate::{
        naive::Naive,
        vm::{Any, ToAny, ToArray, ToObject, error},
    };

    type A = Naive;
    type Thunk = Box<dyn FnOnce() -> Result<Any<A>, Any<A>>>;

    /// A thunk that must not be forced.
    fn boom() -> Result<Any<A>, Any<A>> {
        Err("boom".into())
    }
    /// A fresh arguments array, for a chain whose answer is not the array.
    fn args() -> Result<Any<A>, Any<A>> {
        Ok([7.0.to_any()].to_array().to_any())
    }
    /// Asserts that `chain`, handed a thunk over a fresh arguments array,
    /// answers that very array: a call of `identity` reached its callee.
    /// Arrays compare by identity, so the array is made once and cloned.
    fn answers_arguments(chain: impl FnOnce(Thunk) -> Result<Any<A>, Any<A>>) {
        let a = args().unwrap();
        let thunk = a.clone();
        assert_eq!(chain(Box::new(|| Ok(thunk))), Ok(a));
    }
    /// `{ f: identity, n: 1, u: undefined }`
    fn object() -> Any<A> {
        [
            ("f".into(), identity()),
            ("n".into(), 1.0.to_any()),
            ("u".into(), Any::undefined()),
        ]
        .to_object()
        .to_any()
    }
    fn key(k: &str) -> impl FnOnce() -> Result<Any<A>, Any<A>> {
        let k: Any<A> = k.into();
        || Ok(k)
    }

    // `PropertyLambda`

    /// `a.b` — `end` is the read, throw included.
    #[test]
    fn property_end() {
        assert_eq!(object().dot("n".into()).end(), Ok(1.0.to_any()));
        assert_eq!(
            Any::<A>::undefined().dot("n".into()).end(),
            Err(error::nullish_to_object())
        );
    }

    /// `a.f(...c)`, and `a.b(...c)` on a nullish `a`: the throw waited in
    /// the lambda and `c` was never evaluated.
    #[test]
    fn property_end_call() {
        answers_arguments(|args| object().dot("f".into()).end_call(&rt(), args));
        assert_eq!(
            Any::undefined().dot("f".into()).end_call(&rt(), boom),
            Err(error::nullish_to_object())
        );
    }

    /// A live, non-callable callee: the arguments run before the
    /// callability check, so theirs is the throw.
    #[test]
    fn property_end_call_forces_arguments_before_callability() {
        assert_eq!(
            object().dot("n".into()).end_call(&rt(), boom),
            Err("boom".into())
        );
        assert_eq!(
            object().dot("n".into()).end_call(&rt(), args),
            Err(error::unexpected_type())
        );
    }

    /// `a.b?.(...c)`: guarded on the property, then a region.
    #[test]
    fn property_option_call() {
        answers_arguments(|args| object().dot("f".into()).option_call(&rt(), args).end());
        assert_eq!(
            object().dot("u".into()).option_call(&rt(), boom).end(),
            Ok(Any::undefined())
        );
        assert_eq!(
            object().dot("n".into()).option_call(&rt(), boom).end(),
            Err("boom".into())
        );
        assert_eq!(
            Any::undefined()
                .dot("f".into())
                .option_call(&rt(), boom)
                .end(),
            Err(error::nullish_to_object())
        );
    }

    // `OptionLambda`

    /// `a?.(...c).length` and `a?.().f(...d)`: steps inside the region on
    /// a live value.
    #[test]
    fn option_steps_live() {
        assert_eq!(
            identity().option_call(args).dot(key("length")).end(),
            Ok(1.0.to_any())
        );
        let returns_object: Any<A> = returns(object());
        answers_arguments(|args| {
            returns_object
                .option_call(|| Ok([].to_array().to_any()))
                .dot(key("f"))
                .call(&rt(), args)
                .end()
        });
    }

    /// A skipped region passes through every step, thunks untouched, and
    /// ends as `undefined`.
    #[test]
    fn option_steps_skipped() {
        assert_eq!(
            Any::undefined()
                .option_call(boom)
                .dot(boom)
                .call(&rt(), boom)
                .dot(boom)
                .end(),
            Ok(Any::undefined())
        );
    }

    /// A thrown region passes through every step, thunks untouched, and
    /// ends with its throw.
    #[test]
    fn option_steps_thrown() {
        assert_eq!(
            identity()
                .option_call(boom)
                .dot(key("x"))
                .call(&rt(), args)
                .end(),
            Err("boom".into())
        );
    }

    // `OptionPropertyLambda`

    /// `a?.f(...c)`, `a?.n.x`, `a?.u?.(...c)`, `a?.f?.(...c)`: the three
    /// non-terminal steps on a live chain.
    #[test]
    fn option_property_steps_live() {
        answers_arguments(|args| object().option_dot(key("f")).call(&rt(), args).end());
        assert_eq!(
            object().option_dot(key("n")).dot(key("x")).end(),
            Ok(Any::undefined())
        );
        assert_eq!(
            object().option_dot(key("u")).option_call(&rt(), boom).end(),
            Ok(Any::undefined())
        );
        answers_arguments(|args| object().option_dot(key("f")).option_call(&rt(), args).end());
    }

    /// `a?.b.c(...d).e?.(...f)` on a nullish `a`: one region, everything
    /// skipped.
    #[test]
    fn option_property_steps_skipped() {
        assert_eq!(
            Any::undefined()
                .option_dot(boom)
                .dot(boom)
                .call(&rt(), boom)
                .dot(boom)
                .option_call(&rt(), boom)
                .end(),
            Ok(Any::undefined())
        );
    }

    /// `|()` and `|.` are unguarded: on a live but nullish current value
    /// the thunk is forced and the operation throws — `a?.b()` with `a.b`
    /// undefined throws, it does not answer `undefined`. One case per
    /// unguarded step, so that turning any of them into a guarded step
    /// fails a test.
    #[test]
    fn unguarded_steps_throw_on_nullish_current_value() {
        let returns_undefined: Any<A> = returns(Any::undefined());
        assert_eq!(
            returns_undefined.clone().option_call(args).call(boom).end(),
            Err("boom".into())
        );
        assert_eq!(
            returns_undefined.option_call(args).dot(boom).end(),
            Err("boom".into())
        );
        assert_eq!(
            object().option_dot(key("u")).call(&rt(), boom).end(),
            Err("boom".into())
        );
    }

    /// `|.` on a live but nullish current value throws at the read — after
    /// the key is forced, as JavaScript evaluates `u[k()]`.
    #[test]
    fn option_property_dot_forces_key_before_read() {
        assert_eq!(
            object().option_dot(key("u")).dot(boom).end(),
            Err("boom".into())
        );
        assert_eq!(
            object().option_dot(key("u")).dot(key("x")).end(),
            Err(error::nullish_to_object())
        );
    }

    /// `(a?.f)(...c)` live, and `(a?.b)(...c)` on a nullish `a`: the
    /// parentheses end the region, so the arguments run and `undefined` is
    /// called — the case the host engines disagree on, and the
    /// specification's reading.
    #[test]
    fn option_property_end_call() {
        answers_arguments(|args| object().option_dot(key("f")).end_call(&rt(), args));
        assert_eq!(
            Any::undefined().option_dot(boom).end_call(&rt(), boom),
            Err("boom".into())
        );
        assert_eq!(
            Any::undefined().option_dot(boom).end_call(&rt(), args),
            Err(error::unexpected_type())
        );
    }

    /// A thrown chain stays thrown through `end_call`, arguments untouched.
    #[test]
    fn option_property_end_call_thrown() {
        assert_eq!(
            object().option_dot(boom).end_call(&rt(), boom),
            Err("boom".into())
        );
    }
}