From 0fb787bb720a2a189ab6fa9aeea1564929d50047 Mon Sep 17 00:00:00 2001 From: Jeff Date: Wed, 6 Dec 2023 14:13:22 -0500 Subject: [PATCH] Write docs --- src/abstract_tree/block.rs | 8 ++++ src/abstract_tree/expression.rs | 5 +++ src/abstract_tree/find.rs | 70 --------------------------------- src/abstract_tree/index.rs | 3 ++ src/abstract_tree/logic.rs | 1 + src/abstract_tree/math.rs | 4 ++ src/abstract_tree/while.rs | 3 ++ src/abstract_tree/yield.rs | 3 ++ 8 files changed, 27 insertions(+), 70 deletions(-) delete mode 100644 src/abstract_tree/find.rs diff --git a/src/abstract_tree/block.rs b/src/abstract_tree/block.rs index 42dc1ae..73c33d3 100644 --- a/src/abstract_tree/block.rs +++ b/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, diff --git a/src/abstract_tree/expression.rs b/src/abstract_tree/expression.rs index e62d9d3..38f2131 100644 --- a/src/abstract_tree/expression.rs +++ b/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), diff --git a/src/abstract_tree/find.rs b/src/abstract_tree/find.rs deleted file mode 100644 index 8eba0f1..0000000 --- a/src/abstract_tree/find.rs +++ /dev/null @@ -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 { - 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 { - 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) - } - } -} diff --git a/src/abstract_tree/index.rs b/src/abstract_tree/index.rs index ef63e90..3e06fc7 100644 --- a/src/abstract_tree/index.rs +++ b/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, diff --git a/src/abstract_tree/logic.rs b/src/abstract_tree/logic.rs index 53be0c2..caededb 100644 --- a/src/abstract_tree/logic.rs +++ b/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, diff --git a/src/abstract_tree/math.rs b/src/abstract_tree/math.rs index 538441f..f0369fa 100644 --- a/src/abstract_tree/math.rs +++ b/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, diff --git a/src/abstract_tree/while.rs b/src/abstract_tree/while.rs index d9cbf21..5b53551 100644 --- a/src/abstract_tree/while.rs +++ b/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, diff --git a/src/abstract_tree/yield.rs b/src/abstract_tree/yield.rs index 99dcdc0..6ecdeb0 100644 --- a/src/abstract_tree/yield.rs +++ b/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,