Completed docs, added icon

src/foreign.rs

@@ -18,8 +18,12 @@ use crate::representations::Primitive;
 /// Information returned by [Atomic::run]. This mirrors
 /// [crate::interpreter::Return] but with a clause instead of an Expr.
 pub struct AtomicReturn {
+  /// The next form of the expression
   pub clause: Clause,
+  /// Remaining gas
   pub gas: Option<usize>,
+  /// Whether further normalization is possible by repeated calls to
+  /// [Atomic::run]
   pub inert: bool,
 }
 impl AtomicReturn {
@@ -38,6 +42,7 @@ pub type XfnResult = Result<Clause, RcError>;
 
 /// Errors produced by external code
 pub trait ExternError: Display {
+  /// Convert into trait object
   fn into_extern(self) -> Rc<dyn ExternError>
   where
     Self: 'static + Sized,
@@ -123,21 +128,27 @@ where
 /// to pass control back to the interpreter.btop
 pub struct Atom(pub Box<dyn Atomic>);
 impl Atom {
+  /// Wrap an [Atomic] in a type-erased box
   pub fn new<T: 'static + Atomic>(data: T) -> Self {
     Self(Box::new(data) as Box<dyn Atomic>)
   }
+  /// Get the contained data
   pub fn data(&self) -> &dyn Atomic {
     self.0.as_ref() as &dyn Atomic
   }
+  /// Attempt to downcast contained data to a specific type
   pub fn try_cast<T: Atomic>(&self) -> Option<&T> {
     self.data().as_any().downcast_ref()
   }
+  /// Test the type of the contained data without downcasting
   pub fn is<T: 'static>(&self) -> bool {
     self.data().as_any().is::<T>()
   }
+  /// Downcast contained data, panic if it isn't the specified type
   pub fn cast<T: 'static>(&self) -> &T {
     self.data().as_any().downcast_ref().expect("Type mismatch on Atom::cast")
   }
+  /// Normalize the contained data
   pub fn run(&self, ctx: Context) -> AtomicResult {
     self.0.run(ctx)
   }

src/interner/display.rs

@@ -23,6 +23,7 @@ pub trait InternedDisplay {
     self.bundle(i).to_string()
   }
 
+  /// Combine with an interner to implement [Display]
   fn bundle<'a>(&'a self, interner: &'a Interner) -> DisplayBundle<'a, Self> {
     DisplayBundle { interner, data: self }
   }

src/interner/token.rs

@@ -13,12 +13,15 @@ pub struct Tok<T> {
   phantom_data: PhantomData<T>,
 }
 impl<T> Tok<T> {
+  /// Wrap an ID number into a token
   pub fn from_id(id: NonZeroU32) -> Self {
     Self { id, phantom_data: PhantomData }
   }
+  /// Take the ID number out of a token
   pub fn into_id(self) -> NonZeroU32 {
     self.id
   }
+  /// Cast into usize
   pub fn into_usize(self) -> usize {
     let zero: u32 = self.id.into();
     zero as usize

src/lib.rs

@@ -1,3 +1,7 @@
+#![deny(missing_docs)]
+#![doc(html_logo_url = "../logo.jpg")]
+//! Orchid is a lazy, pure scripting language to be embedded in Rust
+//! applications. Check out the repo for examples and other links.
 pub mod foreign;
 mod foreign_macros;
 pub mod interner;

src/pipeline/error/module_not_found.rs

@@ -5,7 +5,9 @@ use crate::utils::BoxedIter;
 /// Error produced when an import refers to a nonexistent module
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 pub struct ModuleNotFound {
+  /// The file containing the invalid import
   pub file: Vec<String>,
+  /// The invalid import path
   pub subpath: Vec<String>,
 }
 impl ProjectError for ModuleNotFound {

src/pipeline/error/not_exported.rs

@@ -7,9 +7,13 @@ use crate::utils::BoxedIter;
 /// An import refers to a symbol which exists but is not exported.
 #[derive(Debug)]
 pub struct NotExported {
+  /// The containing file - files are always exported
   pub file: Vec<String>,
+  /// The path leading to the unexported module
   pub subpath: Vec<String>,
+  /// The offending file
   pub referrer_file: Vec<String>,
+  /// The module containing the offending import
   pub referrer_subpath: Vec<String>,
 }
 impl ProjectError for NotExported {

src/pipeline/error/parse_error_with_path.rs

@@ -8,8 +8,11 @@ use crate::utils::BoxedIter;
 /// Produced by stages that parse text when it fails.
 #[derive(Debug)]
 pub struct ParseErrorWithPath {
+  /// The complete source of the faulty file
   pub full_source: String,
+  /// The path to the faulty file
   pub path: Vec<String>,
+  /// The parse error produced by Chumsky
   pub error: ParseError,
 }
 impl ProjectError for ParseErrorWithPath {

src/pipeline/error/project_error.rs

@@ -7,7 +7,9 @@ use crate::utils::BoxedIter;
 /// A point of interest in resolving the error, such as the point where
 /// processing got stuck, a command that is likely to be incorrect
 pub struct ErrorPosition {
+  /// The suspected location
   pub location: Location,
+  /// Any information about the role of this location
   pub message: Option<String>,
 }
 

src/pipeline/error/too_many_supers.rs

@@ -9,8 +9,11 @@ use crate::utils::BoxedIter;
 /// than the current module's absolute path
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 pub struct TooManySupers {
+  /// The offending import path
   pub path: Vec<String>,
+  /// The file containing the offending import
   pub offender_file: Vec<String>,
+  /// The module containing the offending import
   pub offender_mod: Vec<String>,
 }
 impl ProjectError for TooManySupers {

src/pipeline/error/unexpected_directory.rs

@@ -6,6 +6,7 @@ use crate::utils::BoxedIter;
 /// a path that refers to a directory
 #[derive(Debug)]
 pub struct UnexpectedDirectory {
+  /// Path to the offending collection
   pub path: Vec<String>,
 }
 impl ProjectError for UnexpectedDirectory {

src/pipeline/error/visibility_mismatch.rs

@@ -8,7 +8,9 @@ use crate::utils::BoxedIter;
 /// Multiple occurences of the same namespace with different visibility
 #[derive(Debug)]
 pub struct VisibilityMismatch {
+  /// The namespace with ambiguous visibility
   pub namespace: Vec<String>,
+  /// The file containing the namespace
   pub file: Rc<Vec<String>>,
 }
 impl ProjectError for VisibilityMismatch {

src/pipeline/file_loader.rs

@@ -33,10 +33,14 @@ impl ProjectError for FileLoadingError {
 /// as the file system.
 #[derive(Clone, PartialEq, Eq, Hash)]
 pub enum Loaded {
+  /// Conceptually equivalent to a sourcefile
   Code(Rc<String>),
+  /// Conceptually equivalent to the list of *.orc files in a folder, without
+  /// the extension
   Collection(Rc<Vec<String>>),
 }
 impl Loaded {
+  /// Is the loaded item source code (not a collection)?
   pub fn is_code(&self) -> bool {
     matches!(self, Loaded::Code(_))
   }

src/pipeline/project_tree/const_tree.rs

@@ -16,7 +16,9 @@ use crate::utils::{pushed, Substack};
 /// describe libraries of external functions in Rust. It implements [Add] for
 /// added convenience
 pub enum ConstTree {
+  /// A function or constant
   Const(Expr),
+  /// A submodule
   Tree(HashMap<Tok<String>, ConstTree>),
 }
 impl ConstTree {

src/representations/ast.rs

@@ -19,7 +19,9 @@ use crate::utils::Substack;
 /// A [Clause] with associated metadata
 #[derive(Clone, Debug, PartialEq)]
 pub struct Expr {
+  /// The actual value
   pub value: Clause,
+  /// Information about the code that produced this value
   pub location: Location,
 }
 
@@ -87,7 +89,9 @@ pub enum PHClass {
 /// Properties of a placeholder that matches unknown tokens in macros
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 pub struct Placeholder {
+  /// Identifier to pair placeholders in the pattern and template
   pub name: Tok<String>,
+  /// The nature of the token set matched by this placeholder
   pub class: PHClass,
 }
 
@@ -321,8 +325,11 @@ impl InternedDisplay for Clause {
 /// A substitution rule as read from the source
 #[derive(Debug, Clone, PartialEq)]
 pub struct Rule {
+  /// Tree fragment in the source code that activates this rule
   pub pattern: Rc<Vec<Expr>>,
+  /// Influences the order in which rules are checked
   pub prio: NotNan<f64>,
+  /// Tree fragment generated by this rule
   pub template: Rc<Vec<Expr>>,
 }
 
@@ -386,7 +393,9 @@ impl InternedDisplay for Rule {
 /// A named constant
 #[derive(Debug, Clone, PartialEq)]
 pub struct Constant {
+  /// Used to reference the constant
   pub name: Tok<String>,
+  /// The constant value inserted where the name is found
   pub value: Expr,
 }
 

src/representations/interpreted.rs

@@ -18,7 +18,9 @@ use crate::utils::sym2string;
 
 /// An expression with metadata
 pub struct Expr {
+  /// The actual value
   pub clause: Clause,
+  /// Information about the code that produced this value
   pub location: Location,
 }
 
@@ -57,10 +59,20 @@ pub struct NotALiteral;
 #[derive(Clone)]
 pub struct ExprInst(pub Rc<RefCell<Expr>>);
 impl ExprInst {
+  /// Read-only access to the shared expression instance
+  ///
+  /// # Panics
+  ///
+  /// if the expression is already borrowed in read-write mode
   pub fn expr(&self) -> impl Deref<Target = Expr> + '_ {
     self.0.as_ref().borrow()
   }
 
+  /// Read-Write access to the shared expression instance
+  ///
+  /// # Panics
+  ///
+  /// if the expression is already borrowed
   pub fn expr_mut(&self) -> impl DerefMut<Target = Expr> + '_ {
     self.0.as_ref().borrow_mut()
   }
@@ -140,11 +152,23 @@ pub enum Clause {
   /// An unintrospectable unit
   P(Primitive),
   /// A function application
-  Apply { f: ExprInst, x: ExprInst },
+  Apply {
+    /// Function to be applied
+    f: ExprInst,
+    /// Argument to be substituted in the function
+    x: ExprInst,
+  },
   /// A name to be looked up in the interpreter's symbol table
   Constant(Sym),
   /// A function
-  Lambda { args: Option<PathSet>, body: ExprInst },
+  Lambda {
+    /// A collection of (zero or more) paths to placeholders belonging to this
+    /// function
+    args: Option<PathSet>,
+    /// The tree produced by this function, with placeholders where the
+    /// argument will go
+    body: ExprInst,
+  },
   /// A placeholder within a function that will be replaced upon application
   LambdaArg,
 }

src/representations/literal.rs

@@ -6,9 +6,13 @@ use ordered_float::NotNan;
 /// external functions
 #[derive(Clone, PartialEq, Eq, Hash)]
 pub enum Literal {
+  /// Any floating point number except `NaN`
   Num(NotNan<f64>),
+  /// An unsigned integer; a size, index or pointer
   Uint(u64),
+  /// A single utf-8 codepoint
   Char(char),
+  /// A utf-8 character sequence
   Str(String),
 }
 

src/representations/location.rs

@@ -8,12 +8,21 @@ use itertools::Itertools;
 /// error. Meaningful within the context of a project.
 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
 pub enum Location {
+  /// Location information lost or code generated on the fly
   Unknown,
+  /// Only the file is known
   File(Rc<Vec<String>>),
-  Range { file: Rc<Vec<String>>, range: Range<usize> },
+  /// Character slice of the code
+  Range {
+    /// Argument to the file loading callback that produced this code
+    file: Rc<Vec<String>>,
+    /// Index of the unicode code points associated with the code
+    range: Range<usize>
+  },
 }
 
 impl Location {
+  /// Range, if known. If the range is known, the file is always known
   pub fn range(&self) -> Option<Range<usize>> {
     if let Self::Range { range, .. } = self {
       Some(range.clone())
@@ -22,6 +31,7 @@ impl Location {
     }
   }
 
+  /// File, if known
   pub fn file(&self) -> Option<Rc<Vec<String>>> {
     if let Self::File(file) | Self::Range { file, .. } = self {
       Some(file.clone())

src/representations/sourcefile.rs

@@ -9,6 +9,12 @@ use crate::utils::{unwrap_or, BoxedIter};
 /// imported or importing all available symbols with a globstar (*)
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct Import {
+  /// Import path, a sequence of module names. Can either start with
+  ///
+  /// - `self` to reference the current module
+  /// - any number of `super` to reference the parent module of the implied
+  ///   `self`
+  /// - a root name
   pub path: Sym,
   /// If name is None, this is a wildcard import
   pub name: Option<Tok<String>>,
@@ -31,25 +37,37 @@ impl Import {
 /// A namespace block
 #[derive(Debug, Clone)]
 pub struct Namespace {
+  /// Name prefixed to all names in the block
   pub name: Tok<String>,
+  /// Prefixed entries
   pub body: Vec<FileEntry>,
 }
 
 /// Things that may be prefixed with an export
 #[derive(Debug, Clone)]
 pub enum Member {
+  /// A substitution rule. Rules apply even when they're not in scope, if the
+  /// absolute names are present eg. because they're produced by other rules
   Rule(Rule),
+  /// A constant (or function) associated with a name
   Constant(Constant),
+  /// A prefixed set of other entries
   Namespace(Namespace),
 }
 
 /// Anything we might encounter in a file
 #[derive(Debug, Clone)]
 pub enum FileEntry {
+  /// Imports one or all names in a module
   Import(Vec<Import>),
+  /// Comments are kept here in case dev tooling wants to parse documentation
   Comment(String),
+  /// An element visible to the outside
   Exported(Member),
+  /// An element only visible from local code
   Internal(Member),
+  /// A list of tokens exported explicitly. This can also create new exported
+  /// tokens that the local module doesn't actually define a role for
   Export(Vec<Tok<String>>),
 }
 

src/representations/tree.rs

@@ -10,23 +10,32 @@ use super::sourcefile::Import;
 use crate::interner::Tok;
 use crate::utils::Substack;
 
+/// The member in a [ModEntry] which is associated with a name in a [Module]
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ModMember<TItem: Clone, TExt: Clone> {
+  /// Arbitrary data
   Item(TItem),
+  /// A child module
   Sub(Rc<Module<TItem, TExt>>),
 }
 
+/// Data about a name in a [Module]
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ModEntry<TItem: Clone, TExt: Clone> {
+  /// The submodule or item
   pub member: ModMember<TItem, TExt>,
+  /// Whether the member is visible to modules other than the parent
   pub exported: bool,
 }
 
 /// A module, containing imports,
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Module<TItem: Clone, TExt: Clone> {
+  /// Import statements present this module
   pub imports: Vec<Import>,
+  /// Submodules and items by name
   pub items: HashMap<Tok<String>, ModEntry<TItem, TExt>>,
+  /// Additional information associated with the module
   pub extra: TExt,
 }
 

src/rule/repository.rs

@@ -46,6 +46,7 @@ pub struct Repository<M: Matcher> {
   cache: Vec<(CachedRule<M>, HashSet<Sym>, NotNan<f64>)>,
 }
 impl<M: Matcher> Repository<M> {
+  /// Build a new repository to hold the given set of rules
   pub fn new(
     mut rules: Vec<Rule>,
     i: &Interner,

src/stl/cpsio/io.rs

@@ -10,7 +10,9 @@ use crate::utils::unwrap_or;
 /// An IO command to be handled by the host application.
 #[derive(Clone, Debug)]
 pub enum IO {
+  /// Print a string to standard output and resume execution
   Print(String, ExprInst),
+  /// Read a line from standard input and pass it to the calback
   Readline(ExprInst),
 }
 atomic_inert!(IO);

src/stl/mk_stl.rs

@@ -6,6 +6,8 @@ use super::str::str;
 use crate::interner::Interner;
 use crate::pipeline::ConstTree;
 
+/// Build the standard library used by the interpreter by combining the other
+/// libraries
 pub fn mk_stl(i: &Interner) -> ConstTree {
   cpsio(i) + conv(i) + bool(i) + str(i) + num(i)
 }

src/stl/mod.rs

@@ -1,3 +1,4 @@
+//! Constants exposed to usercode by the interpreter
 mod assertion_error;
 mod bool;
 mod conv;

src/utils/side.rs

@@ -7,7 +7,9 @@ use super::BoxedIter;
 /// are technically usable for this purpose, they're very easy to confuse
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum Side {
+  /// Left, low, or high-to-low in the case of sequences
   Left,
+  /// Right, high, or low-to-high in the case of sequences
   Right,
 }
 
@@ -21,6 +23,7 @@ impl Display for Side {
 }
 
 impl Side {
+  /// Get the side that is not the current one
   pub fn opposite(&self) -> Self {
     match self {
       Self::Left => Self::Right,

src/utils/substack.rs

@@ -17,7 +17,9 @@ pub struct Stackframe<'a, T> {
 /// the recursion isn't deep enough to warrant a heap-allocated set.
 #[derive(Clone, Copy)]
 pub enum Substack<'a, T> {
+  /// A level in the linked list
   Frame(Stackframe<'a, T>),
+  /// The end of the list
   Bottom,
 }
 
@@ -33,12 +35,16 @@ impl<'a, T> Substack<'a, T> {
   pub fn iter(&self) -> SubstackIterator<T> {
     SubstackIterator { curr: self }
   }
+  /// Add the item to this substack
   pub fn push(&'a self, item: T) -> Self {
     Self::Frame(self.new_frame(item))
   }
+  /// Create a new frame on top of this substack
   pub fn new_frame(&'a self, item: T) -> Stackframe<'a, T> {
     Stackframe { item, prev: self, len: self.opt().map_or(1, |s| s.len) }
   }
+  /// obtain the previous stackframe if one exists
+  /// TODO: this should return a [Substack]
   pub fn pop(&'a self, count: usize) -> Option<&'a Stackframe<'a, T>> {
     if let Self::Frame(p) = self {
       if count == 0 {
@@ -50,12 +56,14 @@ impl<'a, T> Substack<'a, T> {
       None
     }
   }
+  /// number of stackframes
   pub fn len(&self) -> usize {
     match self {
       Self::Frame(f) => f.len,
       Self::Bottom => 0,
     }
   }
+  /// is this the bottom of the stack
   pub fn is_empty(&self) -> bool {
     self.len() == 0
   }