diff --git a/asg/src/checks/mod.rs b/asg/src/checks/mod.rs index 98f973c3e5..d143db3fa2 100644 --- a/asg/src/checks/mod.rs +++ b/asg/src/checks/mod.rs @@ -14,5 +14,7 @@ // You should have received a copy of the GNU General Public License // along with the Leo library. If not, see . +//! Helper methods to determine the correct return value path in an asg. + mod return_path; pub use return_path::*; diff --git a/asg/src/const_value.rs b/asg/src/const_value.rs index 7e82cf9377..8d70a5142b 100644 --- a/asg/src/const_value.rs +++ b/asg/src/const_value.rs @@ -19,6 +19,7 @@ use crate::{AsgConvertError, IntegerType, Span, Type}; use num_bigint::BigInt; use std::{convert::TryInto, fmt}; +/// Constant integer values in a program. #[derive(Clone, Debug, PartialEq)] pub enum ConstInt { I8(i8), @@ -33,11 +34,19 @@ pub enum ConstInt { U128(u128), } +/// Specifies how to calculate a group coordinate in a program. #[derive(Clone, Debug, PartialEq)] pub enum GroupCoordinate { + /// Explicit field element number string. Number(String), + + /// Attempt to recover with a sign high bit. SignHigh, + + /// Attempt to recover with a sign low bit. SignLow, + + /// Try recovering with a sign low - upon failure try sign high. Inferred, } diff --git a/asg/src/error/mod.rs b/asg/src/error/mod.rs index 502953da66..4419793449 100644 --- a/asg/src/error/mod.rs +++ b/asg/src/error/mod.rs @@ -14,6 +14,8 @@ // You should have received a copy of the GNU General Public License // along with the Leo library. If not, see . +//! Errors encountered when attempting to convert to an asg from an ast. + use crate::Span; use leo_ast::Error as FormattedError; use leo_grammar::ParserError; diff --git a/asg/src/expression/circuit_access.rs b/asg/src/expression/circuit_access.rs index d28219bb08..b4f1e3a536 100644 --- a/asg/src/expression/circuit_access.rs +++ b/asg/src/expression/circuit_access.rs @@ -148,7 +148,7 @@ impl FromAst for CircuitAccessExpression if found_member { // skip - } else if circuit.is_input_psuedo_circuit() { + } else if circuit.is_input_pseudo_circuit() { // add new member to implicit input if let Some(expected_type) = expected_type.map(PartialType::full).flatten() { circuit.members.borrow_mut().insert( diff --git a/asg/src/expression/mod.rs b/asg/src/expression/mod.rs index 86d812d8d6..de3c6f6f32 100644 --- a/asg/src/expression/mod.rs +++ b/asg/src/expression/mod.rs @@ -14,6 +14,12 @@ // You should have received a copy of the GNU General Public License // along with the Leo library. If not, see . +//! This module defines an expression node in an asg. +//! +//! Notable differences after conversion from an ast expression include: +//! 1. Storing variable references instead of variable identifiers - better history tracking and mutability +//! 2. Resolving constant values - optimizes execution of program circuit. + mod array_access; pub use array_access::*; diff --git a/asg/src/import.rs b/asg/src/import.rs index c65e29d884..8924530b0f 100644 --- a/asg/src/import.rs +++ b/asg/src/import.rs @@ -14,6 +14,8 @@ // You should have received a copy of the GNU General Public License // along with the Leo library. If not, see . +//! Helper methods for resolving imported packages. + use crate::{AsgConvertError, Program, Span}; use indexmap::IndexMap; diff --git a/asg/src/input.rs b/asg/src/input.rs index 32aa4ae7ff..18023bd6fd 100644 --- a/asg/src/input.rs +++ b/asg/src/input.rs @@ -22,6 +22,7 @@ use std::{ sync::{Arc, Weak}, }; +/// Stores program input values as asg nodes. #[derive(Clone)] pub struct Input { pub registers: Arc, @@ -32,11 +33,11 @@ pub struct Input { pub container: Variable, } -pub const CONTAINER_PSUEDO_CIRCUIT: &str = "$InputContainer"; -pub const REGISTERS_PSUEDO_CIRCUIT: &str = "$InputRegister"; -pub const RECORD_PSUEDO_CIRCUIT: &str = "$InputRecord"; -pub const STATE_PSUEDO_CIRCUIT: &str = "$InputState"; -pub const STATE_LEAF_PSUEDO_CIRCUIT: &str = "$InputStateLeaf"; +pub const CONTAINER_PSEUDO_CIRCUIT: &str = "$InputContainer"; +pub const REGISTERS_PSEUDO_CIRCUIT: &str = "$InputRegister"; +pub const RECORD_PSEUDO_CIRCUIT: &str = "$InputRecord"; +pub const STATE_PSEUDO_CIRCUIT: &str = "$InputState"; +pub const STATE_LEAF_PSEUDO_CIRCUIT: &str = "$InputStateLeaf"; impl Input { fn make_header(name: &str) -> Arc { @@ -61,10 +62,10 @@ impl Input { } pub fn new(scope: &Scope) -> Self { - let registers = Self::make_header(REGISTERS_PSUEDO_CIRCUIT); - let record = Self::make_header(RECORD_PSUEDO_CIRCUIT); - let state = Self::make_header(STATE_PSUEDO_CIRCUIT); - let state_leaf = Self::make_header(STATE_LEAF_PSUEDO_CIRCUIT); + let registers = Self::make_header(REGISTERS_PSEUDO_CIRCUIT); + let record = Self::make_header(RECORD_PSEUDO_CIRCUIT); + let state = Self::make_header(STATE_PSEUDO_CIRCUIT); + let state_leaf = Self::make_header(STATE_LEAF_PSEUDO_CIRCUIT); let mut container_members = IndexMap::new(); container_members.insert( @@ -86,7 +87,7 @@ impl Input { let container_circuit = Arc::new(Circuit { id: uuid::Uuid::new_v4(), - name: RefCell::new(Identifier::new(CONTAINER_PSUEDO_CIRCUIT.to_string())), + name: RefCell::new(Identifier::new(CONTAINER_PSEUDO_CIRCUIT.to_string())), body: RefCell::new(Weak::new()), members: RefCell::new(container_members), core_mapping: RefCell::new(None), @@ -137,10 +138,10 @@ impl Input { } impl Circuit { - pub fn is_input_psuedo_circuit(&self) -> bool { + pub fn is_input_pseudo_circuit(&self) -> bool { matches!( &*self.name.borrow().name, - REGISTERS_PSUEDO_CIRCUIT | RECORD_PSUEDO_CIRCUIT | STATE_PSUEDO_CIRCUIT | STATE_LEAF_PSUEDO_CIRCUIT + REGISTERS_PSEUDO_CIRCUIT | RECORD_PSEUDO_CIRCUIT | STATE_PSEUDO_CIRCUIT | STATE_LEAF_PSEUDO_CIRCUIT ) } } diff --git a/asg/src/lib.rs b/asg/src/lib.rs index db207af27c..6e26852f07 100644 --- a/asg/src/lib.rs +++ b/asg/src/lib.rs @@ -13,6 +13,15 @@ // You should have received a copy of the GNU General Public License // along with the Leo library. If not, see . + +//! The abstract semantic graph (asg) for a Leo program. +//! +//! This module contains the [`Asg`] type, an abstract data type that represents a Leo program +//! as a series of graph nodes. The [`Asg`] type is at a greater level of abstraction than an [`Ast`]. +//! +//! A new [`Asg`] type can be created from an [`Ast`]. +//! Converting to an [`Asg`] provides greater type safety by canonicalizing and checking program types. + #![allow(clippy::from_over_into)] #[macro_use] extern crate thiserror; @@ -63,13 +72,12 @@ pub use leo_ast::{Identifier, Span}; use std::path::Path; -/// The abstract syntax graph (asg) for a Leo program. +/// The abstract semantic graph (asg) for a Leo program. /// /// The [`Asg`] type represents a Leo program as a series of recursive data types. -/// These data types form a graph that begins from a [`Program`] type root. +/// These data types form a graph that begins from a [`Program`] type node. /// /// A new [`Asg`] can be created from an [`Ast`] generated in the `ast` module. -// TODO (protryon): please uncomment and mirror the implementation from Ast. This should be the only entrypoint called by the compiler module. // #[derive(Debug, Eq, PartialEq)] // pub struct Asg { // asg: InnerProgram, diff --git a/asg/src/node.rs b/asg/src/node.rs index 3e56ce9a0c..e121a3c9f4 100644 --- a/asg/src/node.rs +++ b/asg/src/node.rs @@ -16,6 +16,7 @@ use crate::{AsgConvertError, PartialType, Scope, Span}; +/// A node in the abstract semantic graph. pub trait Node { fn span(&self) -> Option<&Span>; } diff --git a/asg/src/program/mod.rs b/asg/src/program/mod.rs index 061fb4c7d8..3c549a37aa 100644 --- a/asg/src/program/mod.rs +++ b/asg/src/program/mod.rs @@ -14,6 +14,10 @@ // You should have received a copy of the GNU General Public License // along with the Leo library. If not, see . +//! This module defines the program node for an asg. +//! +//! + mod circuit; pub use circuit::*; diff --git a/asg/src/reducer/mod.rs b/asg/src/reducer/mod.rs index f471d9511d..95f82553eb 100644 --- a/asg/src/reducer/mod.rs +++ b/asg/src/reducer/mod.rs @@ -14,6 +14,9 @@ // You should have received a copy of the GNU General Public License // along with the Leo library. If not, see . +//! This module contains the reducer which iterates through ast nodes - converting them into +//! asg nodes and saving relevant information. + mod monoid; pub use monoid::*; diff --git a/asg/src/scope.rs b/asg/src/scope.rs index 2a8114f2bd..4092e804a6 100644 --- a/asg/src/scope.rs +++ b/asg/src/scope.rs @@ -14,14 +14,12 @@ // You should have received a copy of the GNU General Public License // along with the Leo library. If not, see . -// TODO (protryon): Please order dependencies in two groups alphabetically 1. Our dependencies 2. Everyone else's use crate::{AsgConvertError, Circuit, Function, Input, Type, Variable}; use indexmap::IndexMap; use std::{cell::RefCell, sync::Arc}; use uuid::Uuid; -// TODO (protryon): Struct defs should have a description of the data type and field. /// An abstract data type that track the current bindings for variables, functions, and circuits. pub struct InnerScope { /// The unique id of the scope. @@ -52,9 +50,8 @@ pub struct InnerScope { pub type Scope = Arc>; impl InnerScope { - // TODO (protryon): Function definitions should have one extra line above and below the description. /// - /// Returns a reference to the variable corresponding to the name. TODO (protryon): The description should clearly state the function's return and given arguments. + /// Returns a reference to the variable corresponding to the name. /// /// If the current scope did not have this name present, then the parent scope is checked. /// If there is no parent scope, then `None` is returned. diff --git a/asg/src/statement/mod.rs b/asg/src/statement/mod.rs index 910ca629b2..51477a4532 100644 --- a/asg/src/statement/mod.rs +++ b/asg/src/statement/mod.rs @@ -14,6 +14,10 @@ // You should have received a copy of the GNU General Public License // along with the Leo library. If not, see . +//! This module defines a statement node in an asg. +//! +//! Ast statement nodes can be directly converted into asg nodes with no major differences. + mod assign; pub use assign::*; diff --git a/asg/src/type_.rs b/asg/src/type_.rs index 2ffabeefba..ac71b3b8c7 100644 --- a/asg/src/type_.rs +++ b/asg/src/type_.rs @@ -22,6 +22,7 @@ use std::{ sync::{Arc, Weak}, }; +/// A type in an asg. #[derive(Clone, PartialEq)] pub enum Type { // Data types @@ -37,12 +38,14 @@ pub enum Type { Circuit(Arc), } +/// TODO (@protryon): Please provide comments. #[derive(Clone)] pub enum WeakType { Type(Type), // circuit not allowed Circuit(Weak), } +/// TODO (@protryon): Please provide comments. #[derive(Clone, PartialEq)] pub enum PartialType { Type(Type), // non-array or tuple diff --git a/asg/src/variable.rs b/asg/src/variable.rs index 59cc32b949..2314c853f1 100644 --- a/asg/src/variable.rs +++ b/asg/src/variable.rs @@ -23,6 +23,7 @@ use std::{ }; use uuid::Uuid; +/// Specifies how a program variable was declared. pub enum VariableDeclaration { Definition, IterationDefinition, @@ -30,6 +31,7 @@ pub enum VariableDeclaration { Input, } +/// Stores information on a program variable. pub struct InnerVariable { pub id: Uuid, pub name: Identifier,