From a78d560a0d6d61b43d5ca61d21fc23ba5a80d2fb Mon Sep 17 00:00:00 2001 From: Jeff Date: Tue, 13 Aug 2024 18:27:03 -0400 Subject: [PATCH] Add docs --- dust-lang/src/abstract_tree.rs | 10 +++++++--- dust-lang/src/lib.rs | 16 +++++++++++++++- dust-lang/src/vm.rs | 6 ++++++ 3 files changed, 28 insertions(+), 4 deletions(-) diff --git a/dust-lang/src/abstract_tree.rs b/dust-lang/src/abstract_tree.rs index 7cd22ef..2700e47 100644 --- a/dust-lang/src/abstract_tree.rs +++ b/dust-lang/src/abstract_tree.rs @@ -34,6 +34,7 @@ impl Display for Node { #[derive(Debug, Clone, Eq, PartialEq, PartialOrd, Ord, Serialize, Deserialize)] pub enum Statement { + // Assignment does not return a value, but has a side effect on the context Assignment { identifier: Node, operator: Node, @@ -43,7 +44,7 @@ pub enum Statement { // A sequence of statements Block(Vec>), - // Assignment, logic, math and comparison expressions with two operands + // Logic, math and comparison expressions with two operands BinaryOperation { left: Box>, operator: Node, @@ -100,7 +101,10 @@ pub enum Statement { else_body: Box>, }, - // Identifier expression + // Identifier + // + // Identifier statements in the syntax tree (i.e. Node) are evaluated as + // expressions or reconstructed into a Node by the parser Identifier(Identifier), // Value collection expressions @@ -111,7 +115,7 @@ pub enum Statement { Constant(Value), // A statement that always returns None. Created with a semicolon, it causes the preceding - // statement to return None. This is analagous to the semicolon or unit type in Rust. + // statement to return None. This is analagous to the semicolon in Rust. Nil(Box>), } diff --git a/dust-lang/src/lib.rs b/dust-lang/src/lib.rs index 2a4deff..f8bd0d7 100644 --- a/dust-lang/src/lib.rs +++ b/dust-lang/src/lib.rs @@ -1,6 +1,20 @@ //! The Dust programming language. //! -//! Dust is a statically typed, interpreted programming language. +//! To get started, you can use the `run` function to run a Dust program. +//! +//! ```rust +//! use dust_lang::{run, Value}; +//! +//! let program = " +//! foo = 21 +//! bar = 2 +//! foo * bar +//! "; +//! +//! let the_answer = run(program).unwrap(); +//! +//! assert_eq!(the_answer, Some(Value::integer(42))); +//! ``` pub mod abstract_tree; pub mod analyzer; pub mod built_in_function; diff --git a/dust-lang/src/vm.rs b/dust-lang/src/vm.rs index f8b46c3..29481f9 100644 --- a/dust-lang/src/vm.rs +++ b/dust-lang/src/vm.rs @@ -63,6 +63,12 @@ pub fn run_with_context(source: &str, context: Context) -> Result, .map_err(|vm_error| DustError::VmError { vm_error, source }) } +/// Dust virtual machine. +/// +/// **Warning**: Do not run an AbstractSyntaxTree that has not been analyzed. Use the `run` or +/// `run_with_context` functions to make sure the program is analyzed before running it. +/// +/// See the `run_with_context` function for an example of how to use the Analyzer and the VM. pub struct Vm { abstract_tree: AbstractSyntaxTree, context: Context,