189: Effect Handlers — Introduction

// Effect Handlers Intro — Simulated Algebraic Effects in Rust
//
// OCaml 5 has native algebraic effects.  Rust does not, but we can simulate
// the same pattern with the interpreter/visitor pattern:
//
//   * Define an "effect" as a request type.
//   * The "program" is a free-monad-like structure that issues requests.
//   * The "handler" is an interpreter that decides what to do for each request.
//
// DSL: Print a string / Readline — two effects.

// ── Effect requests ──────────────────────────────────────────────────────────

enum Effect {
    Print(String),
    Readline,
}

// ── A program step ───────────────────────────────────────────────────────────

enum Step<A> {
    Done(A),
    // Issue an effect; the continuation expects the "return value" of that effect.
    Effect(Effect, Box<dyn FnOnce(EffectResult) -> Step<A>>),
}

enum EffectResult {
    Unit,
    Line(String),
}

// ── Smart constructors ───────────────────────────────────────────────────────

fn done<A>(x: A) -> Step<A> {
    Step::Done(x)
}

fn print_effect<A: 'static>(msg: impl Into<String>, next: Step<A>) -> Step<A> {
    Step::Effect(
        Effect::Print(msg.into()),
        Box::new(move |_| next),
    )
}

fn readline_effect<A: 'static, F: FnOnce(String) -> Step<A> + 'static>(f: F) -> Step<A> {
    Step::Effect(
        Effect::Readline,
        Box::new(move |r| match r {
            EffectResult::Line(s) => f(s),
            _ => panic!("expected Line result"),
        }),
    )
}

fn bind_step<A: 'static, B: 'static, F: FnOnce(A) -> Step<B> + 'static>(
    step: Step<A>,
    f: F,
) -> Step<B> {
    match step {
        Step::Done(x) => f(x),
        Step::Effect(eff, cont) => {
            Step::Effect(eff, Box::new(move |r| bind_step(cont(r), f)))
        }
    }
}

// ── Handler trait ────────────────────────────────────────────────────────────

trait Handler {
    fn handle_print(&mut self, msg: &str) -> EffectResult;
    fn handle_readline(&mut self) -> EffectResult;
}

fn run_with<A, H: Handler>(mut handler: H, mut step: Step<A>) -> (A, H) {
    loop {
        match step {
            Step::Done(x) => return (x, handler),
            Step::Effect(Effect::Print(msg), cont) => {
                let r = handler.handle_print(&msg);
                step = cont(r);
            }
            Step::Effect(Effect::Readline, cont) => {
                let r = handler.handle_readline();
                step = cont(r);
            }
        }
    }
}

// ── Handler 1: pure simulation ────────────────────────────────────────────

struct PureHandler {
    inputs: std::collections::VecDeque<String>,
    output: String,
}

impl PureHandler {
    fn new(inputs: &[&str]) -> Self {
        PureHandler {
            inputs: inputs.iter().map(|s| s.to_string()).collect(),
            output: String::new(),
        }
    }
}

impl Handler for PureHandler {
    fn handle_print(&mut self, msg: &str) -> EffectResult {
        self.output.push_str(msg);
        self.output.push('\n');
        EffectResult::Unit
    }

    fn handle_readline(&mut self) -> EffectResult {
        EffectResult::Line(self.inputs.pop_front().unwrap_or_default())
    }
}

// ── Handler 2: real I/O ───────────────────────────────────────────────────

struct IoHandler;

impl Handler for IoHandler {
    fn handle_print(&mut self, msg: &str) -> EffectResult {
        println!("{}", msg);
        EffectResult::Unit
    }

    fn handle_readline(&mut self) -> EffectResult {
        let mut line = String::new();
        std::io::stdin().read_line(&mut line).unwrap();
        EffectResult::Line(line.trim_end().to_string())
    }
}

// ── Example program: interactive greeting ────────────────────────────────

fn interactive_program() -> Step<String> {
    print_effect(
        "What is your name?",
        readline_effect(|name| {
            let greeting = format!("Hello, {}!", name);
            print_effect(greeting, done(name))
        }),
    )
}

fn main() {
    // ── Pure simulation ───────────────────────────────────────────────
    let handler = PureHandler::new(&["OCaml 5"]);
    let (result, handler) = run_with(handler, interactive_program());
    println!("Output:\n{}", handler.output.trim());
    println!("Got name: {}", result);
    println!();

    // ── Real I/O handler (uncomment to test interactively) ────────────
    // let (_result, _) = run_with(IoHandler, interactive_program());
    println!("(Real I/O handler available — uncomment to use interactively)");
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_greeting_output() {
        let handler = PureHandler::new(&["Rust"]);
        let (name, handler) = run_with(handler, interactive_program());
        assert_eq!(name, "Rust");
        assert!(handler.output.contains("Hello, Rust!"));
        assert!(handler.output.contains("What is your name?"));
    }

    #[test]
    fn test_pure_handler_no_real_io() {
        // Multiple readline calls
        let prog = readline_effect(|a| {
            readline_effect(move |b| done(format!("{} {}", a, b)))
        });
        let handler = PureHandler::new(&["hello", "world"]);
        let (result, _) = run_with(handler, prog);
        assert_eq!(result, "hello world");
    }

    #[test]
    fn test_print_collects_output() {
        let prog = bind_step(
            print_effect("line1", done(())),
            |_| print_effect("line2", done(42i32)),
        );
        let handler = PureHandler::new(&[]);
        let (val, h) = run_with(handler, prog);
        assert_eq!(val, 42);
        assert!(h.output.contains("line1"));
        assert!(h.output.contains("line2"));
    }
}