Public API and docs

src/interpreter/apply.rs

@@ -53,12 +53,16 @@ fn map_at<E>(
     .map(|p| p.0)
 }
 
+/// TODO replace when `!` gets stabilized
+#[derive(Debug)]
+enum Never {}
+
 /// Replace the [Clause::LambdaArg] placeholders at the ends of the [PathSet]
 /// with the value in the body. Note that a path may point to multiple
 /// placeholders.
 fn substitute(paths: &PathSet, value: Clause, body: ExprInst) -> ExprInst {
   let PathSet { steps, next } = paths;
-  map_at(steps, body, &mut |checkpoint| -> Result<Clause, !> {
+  map_at(steps, body, &mut |checkpoint| -> Result<Clause, Never> {
     match (checkpoint, next) {
       (Clause::Lambda { .. }, _) => unreachable!("Handled by map_at"),
       (Clause::Apply { f, x }, Some((left, right))) => Ok(Clause::Apply {
@@ -72,7 +76,7 @@ fn substitute(paths: &PathSet, value: Clause, body: ExprInst) -> ExprInst {
         panic!("Substitution path leads into something other than Apply"),
     }
   })
-  .into_ok()
+  .unwrap()
 }
 
 /// Apply a function-like expression to a parameter.

src/interpreter/context.rs

@@ -8,8 +8,8 @@ use crate::representations::interpreted::ExprInst;
 pub struct Context<'a> {
   /// Table used to resolve constants
   pub symbols: &'a HashMap<Sym, ExprInst>,
-  /// The interner used for strings internally, so external functions can deduce
-  /// referenced constant names on the fly
+  /// The interner used for strings internally, so external functions can
+  /// deduce referenced constant names on the fly
   pub interner: &'a Interner,
   /// The number of reduction steps the interpreter can take before returning
   pub gas: Option<usize>,

src/interpreter/error.rs

@@ -7,7 +7,9 @@ use crate::representations::interpreted::ExprInst;
 /// Problems in the process of execution
 #[derive(Clone, Debug)]
 pub enum RuntimeError {
+  /// A Rust function encountered an error
   Extern(Rc<dyn ExternError>),
+  /// Primitive applied as function
   NonFunctionApplication(ExprInst),
 }
 

src/interpreter/mod.rs

@@ -1,3 +1,4 @@
+//! functions to interact with Orchid code
 mod apply;
 mod context;
 mod error;
@@ -5,4 +6,4 @@ mod run;
 
 pub use context::{Context, Return};
 pub use error::RuntimeError;
-pub use run::{run, run_handler, Handler, HandlerParm, HandlerRes};
+pub use run::{run, run_handler, Handler, HandlerErr, HandlerParm, HandlerRes};

src/interpreter/run.rs

@@ -78,23 +78,24 @@ impl From<HandlerParm> for HandlerErr {
   }
 }
 
-/// Various possible outcomes of a [Handler] execution.
+/// Various possible outcomes of a [Handler] execution. Ok returns control to
+/// the interpreter. The meaning of Err is decided by the value in it.
 pub type HandlerRes = Result<ExprInst, HandlerErr>;
 
 /// A trait for things that may be able to handle commands returned by Orchid
-/// code. This trait is implemented for [FnMut(HandlerParm) -> HandlerRes] and
-/// [(Handler, Handler)], users are not supposed to implement it themselves.
+/// code. This trait is implemented for `FnMut(HandlerParm) -> HandlerRes` and
+/// `(Handler, Handler)`, users are not supposed to implement it themselves.
 ///
 /// A handler receives an arbitrary inert [Atomic] and uses [Atomic::as_any]
-/// then [std::any::Any::downcast_ref] to obtain a known type. If this fails, it
-/// returns the box in [HandlerErr::NA] which will be passed to the next
+/// then downcast_ref of [std::any::Any] to obtain a known type. If this fails,
+/// it returns the box in [HandlerErr::NA] which will be passed to the next
 /// handler.
 pub trait Handler {
   /// Attempt to resolve a command with this handler.
   fn resolve(&mut self, data: HandlerParm) -> HandlerRes;
 
   /// If this handler isn't applicable, try the other one.
-  fn or<T: Handler>(self, t: T) -> impl Handler
+  fn or<T: Handler>(self, t: T) -> (Self, T)
   where
     Self: Sized,
   {