Write docs

src/abstract_tree/block.rs

@@ -6,6 +6,14 @@ use tree_sitter::Node;
 
 use crate::{AbstractTree, Error, Map, Result, Statement, Type, Value};
 
+/// Abstract representation of a block.
+///
+/// A block is almost identical to the root except that it must have curly
+/// braces and can optionally be asynchronous. A block evaluates to the value of
+/// its final statement but an async block will short-circuit if a statement
+/// results in an error. Note that this will be the first statement to encounter
+/// an error at runtime, not necessarilly the first statement as they are
+/// written.
 #[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq, PartialOrd, Ord)]
 pub struct Block {
     is_async: bool,

src/abstract_tree/expression.rs

@@ -7,6 +7,11 @@ use crate::{
 
 use super::{function_call::FunctionCall, logic::Logic, math::Math};
 
+/// Abstract representation of an expression statement.
+///
+/// Unlike statements, which can involve complex logic, an expression is
+/// expected to evaluate to a value. However, an expression can still contain
+/// nested statements and may evaluate to an empty value.
 #[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq, PartialOrd, Ord)]
 pub enum Expression {
     Value(ValueNode),

src/abstract_tree/find.rs

@@ -1,70 +0,0 @@
-use rayon::prelude::*;
-use serde::{Deserialize, Serialize};
-use tree_sitter::Node;
-
-use crate::{AbstractTree, Block, Error, Expression, Identifier, Map, Result, Value};
-
-#[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq, PartialOrd, Ord)]
-pub struct Find {
-    identifier: Identifier,
-    expression: Expression,
-    item: Block,
-}
-
-impl AbstractTree for Find {
-    fn from_syntax_node(source: &str, node: Node) -> Result<Self> {
-        let identifier_node = node.child(1).unwrap();
-        let identifier = Identifier::from_syntax_node(source, identifier_node)?;
-
-        let expression_node = node.child(3).unwrap();
-        let expression = Expression::from_syntax_node(source, expression_node)?;
-
-        let item_node = node.child(4).unwrap();
-        let item = Block::from_syntax_node(source, item_node)?;
-
-        Ok(Find {
-            identifier,
-            expression,
-            item,
-        })
-    }
-
-    fn run(&self, source: &str, context: &mut Map) -> Result<Value> {
-        let expression_run = self.expression.run(source, context)?;
-        let list = expression_run.as_list()?.items();
-        let key = self.identifier.inner();
-
-        let find_result = list.par_iter().find_map_first(|value| {
-            let loop_context = Map::clone_from(context).unwrap();
-
-            loop_context
-                .variables_mut()
-                .unwrap()
-                .insert(key.clone(), (*value).clone());
-
-            let run_result = self.item.run(source, &mut loop_context.clone());
-
-            if let Ok(run_result_value) = run_result {
-                if let Ok(should_return) = run_result_value.as_boolean() {
-                    if should_return {
-                        Some(Ok(value.clone()))
-                    } else {
-                        None
-                    }
-                } else {
-                    Some(Err(Error::ExpectedBoolean {
-                        actual: value.clone(),
-                    }))
-                }
-            } else {
-                Some(run_result)
-            }
-        });
-
-        if let Some(result) = find_result {
-            result
-        } else {
-            Ok(Value::Empty)
-        }
-    }
-}

src/abstract_tree/index.rs

@@ -3,6 +3,9 @@ use tree_sitter::Node;
 
 use crate::{AbstractTree, Error, Expression, List, Map, Result, Type, Value};
 
+/// Abstract representation of an index expression.
+///
+/// An index is a means of accessing values stored in list, maps and strings.
 #[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq, PartialOrd, Ord)]
 pub struct Index {
     pub collection: Expression,

src/abstract_tree/logic.rs

@@ -3,6 +3,7 @@ use tree_sitter::Node;
 
 use crate::{AbstractTree, Error, Expression, Map, Result, Type, Value};
 
+/// Abstract representation of a logic expression.
 #[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq, PartialOrd, Ord)]
 pub struct Logic {
     left: Expression,

src/abstract_tree/math.rs

@@ -3,6 +3,10 @@ use tree_sitter::Node;
 
 use crate::{AbstractTree, Error, Expression, Map, Result, Type, Value};
 
+/// Abstract representation of a math operation.
+///
+/// Dust currently supports the four basic operations and the modulo (or
+/// remainder) operator.
 #[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq, PartialOrd, Ord)]
 pub struct Math {
     left: Expression,

src/abstract_tree/while.rs

@@ -3,6 +3,9 @@ use tree_sitter::Node;
 
 use crate::{AbstractTree, Block, Expression, Map, Result, Type, Value};
 
+/// Abstract representation of a while loop.
+///
+/// While executes its block repeatedly until its expression evaluates to true.
 #[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq, PartialOrd, Ord)]
 pub struct While {
     expression: Expression,

src/abstract_tree/yield.rs

@@ -3,6 +3,9 @@ use tree_sitter::Node;
 
 use crate::{AbstractTree, Expression, FunctionCall, Map, Result, Type, Value};
 
+/// Abstract representation of a yield expression.
+///
+/// Yield is an alternate means of calling and passing values to a function.
 #[derive(Debug, Clone, Serialize, Deserialize, Eq, PartialEq, PartialOrd, Ord)]
 pub struct Yield {
     call: FunctionCall,