diff --git a/CHANGELOG.md b/CHANGELOG.md index d652bf49bd..a9ff054a3e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,15 @@ #### Upcoming Changes -* perf: changed `ok_or` usage for `ok_or_else` in expensive cases [#1332](https://github.com/lambdaclass/cairo-vm/pull/1332) +* docs: improved crate documentation [#1334](https://github.com/lambdaclass/cairo-vm/pull/1334) + +* chore!: made `deserialize_utils` module private [#1334](https://github.com/lambdaclass/cairo-vm/pull/1334) + BREAKING: + * `deserialize_utils` is no longer exported + * functions `maybe_add_padding`, `parse_value`, and `take_until_unbalanced` are no longer exported + * `ReferenceParseError` is no more -* feat: add `arbitrary` feature to enable arbitrary derive in `Program` and `CairoRunConfig` [#1306](https://github.com/lambdaclass/cairo-vm/pull/1306) +* perf: changed `ok_or` usage for `ok_or_else` in expensive cases [#1332](https://github.com/lambdaclass/cairo-vm/pull/1332) * feat: updated the old WASM example and moved it to [`examples/wasm-demo`](examples/wasm-demo/) [#1315](https://github.com/lambdaclass/cairo-vm/pull/1315) diff --git a/fuzzer/Cargo.lock b/fuzzer/Cargo.lock index efdf8ae22a..b11909e680 100644 --- a/fuzzer/Cargo.lock +++ b/fuzzer/Cargo.lock @@ -169,6 +169,7 @@ checksum = "a3e2c3daef883ecc1b5d58c15adae93470a91d425f3532ba1695849656af3fc1" name = "cairo-felt" version = "0.8.2" dependencies = [ + "arbitrary", "lazy_static", "num-bigint", "num-integer", @@ -181,6 +182,7 @@ name = "cairo-vm" version = "0.8.2" dependencies = [ "anyhow", + "arbitrary", "bincode", "bitvec", "cairo-felt", @@ -590,6 +592,7 @@ version = "0.4.3" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "f93ab6289c7b344a8a9f60f88d80aa20032336fe78da341afc91c8a2341fc75f" dependencies = [ + "arbitrary", "autocfg", "num-integer", "num-traits", diff --git a/vm/src/lib.rs b/vm/src/lib.rs index c6387994c4..23205cc8d2 100644 --- a/vm/src/lib.rs +++ b/vm/src/lib.rs @@ -1,9 +1,14 @@ -//! An implementation of the Cairo virtual machine +//! # An implementation of the Cairo virtual machine //! -//! # Feature Flags +//! ## Feature Flags +//! - `std`: Enables usage of the [`std`] standard library. Enabled by default. //! - `skip_next_instruction_hint`: Enable the `skip_next_instruction()` hint. Not enabled by default. -//! - `hooks`: Enable [Hooks](vm::hooks) support for the [VirtualMachine](vm::vm_core::VirtualMachine). Not enabled by default. -//! - `with_mimalloc`: Use [MiMalloc](https://crates.io/crates/mimalloc) as the program global allocator. +//! - `hooks`: Enable [`Hooks`](crate::vm::hooks::Hooks) support for the [VirtualMachine](vm::vm_core::VirtualMachine). Not enabled by default. +//! - `test_utils`: Enables test utils (`hooks` and `skip_next_instruction` features). Not enabled by default. +//! - `with_mimalloc`: Use [`MiMalloc`](https://crates.io/crates/mimalloc) as the program global allocator. +//! - `cairo-1-hints`: Enable hints that were introduced in Cairo 1. Not enabled by default. +//! - `arbitrary`: Enables implementations of [`arbitrary::Arbitrary`](https://docs.rs/arbitrary/latest/arbitrary/) for some structs. Not enabled by default. +//! - `lambdaworks-felt`: Enables usage of the [**lambdaworks**](https://github.com/lambdaclass/lambdaworks) backend for [`felt::Felt252`]. Not enabled by default. #![cfg_attr(docsrs, feature(doc_cfg))] #![deny(warnings)] diff --git a/vm/src/serde/deserialize_program.rs b/vm/src/serde/deserialize_program.rs index dd114630c8..ca7b777fa0 100644 --- a/vm/src/serde/deserialize_program.rs +++ b/vm/src/serde/deserialize_program.rs @@ -1,3 +1,11 @@ +//! # Program deserialization +//! +//! This module contains the logic for [`Program`] deserialization. +//! Users shouldn't need to use it directly (except for [`BuiltinName`]). +//! +//! To generate a [`Program`] from a JSON string, see [`Program::from_bytes()`]. +//! To do the same from a JSON file, see [`Program::from_file()`]. + use crate::stdlib::{collections::HashMap, fmt, prelude::*, sync::Arc}; use crate::vm::runners::builtin_runner::SEGMENT_ARENA_BUILTIN_NAME; diff --git a/vm/src/serde/deserialize_utils.rs b/vm/src/serde/deserialize_utils.rs index a11eb2f8de..5a90ec863d 100644 --- a/vm/src/serde/deserialize_utils.rs +++ b/vm/src/serde/deserialize_utils.rs @@ -1,10 +1,16 @@ -use crate::stdlib::{fmt, num::ParseIntError, prelude::*, str::FromStr}; - +//! # Deserialization utils +//! +//! This module contains some helper functions used in [`Program`](crate::types::program::Program) deserialization. +//! Namely, [`maybe_add_padding`] and [`parse_value`]. +//! +//! See [the docs](/docs/references_parsing/README.md) for context and grammar explanation. + +use crate::stdlib::{prelude::*, str::FromStr}; use crate::{ serde::deserialize_program::{OffsetValue, ValueAddress}, types::instruction::Register, }; -use felt::{Felt252, ParseFeltError}; +use felt::Felt252; use nom::{ branch::alt, bytes::{ @@ -19,35 +25,9 @@ use nom::{ }; use num_integer::Integer; -#[derive(Debug, PartialEq, Eq)] -pub enum ReferenceParseError { - IntError(ParseIntError), - Felt252Error(ParseFeltError), - InvalidStringError(String), -} - -impl fmt::Display for ReferenceParseError { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { - match self { - ReferenceParseError::IntError(error) => { - write!(f, "Int parsing error: ")?; - error.fmt(f) - } - ReferenceParseError::Felt252Error(error) => { - write!(f, "Felt252 parsing error: ")?; - error.fmt(f) - } - ReferenceParseError::InvalidStringError(error) => { - write!(f, "Invalid reference string error: ")?; - error.fmt(f) - } - } - } -} - // Checks if the hex string has an odd length. // If that is the case, prepends '0' to it. -pub fn maybe_add_padding(mut hex: String) -> String { +pub(crate) fn maybe_add_padding(mut hex: String) -> String { if hex.len().is_odd() { hex.insert(0, '0'); return hex; @@ -55,11 +35,9 @@ pub fn maybe_add_padding(mut hex: String) -> String { hex } -/* -NOM PARSERS -See the docs for context and grammar explanation: -cleopatra_cairo/docs/references_parsing/README.md -*/ +// ----------------------- +// NOM PARSERS +// ----------------------- // Checks if the input has outer brackets. This is used to set // the `dereference` field of ValueAddress. @@ -162,7 +140,7 @@ fn no_inner_dereference(input: &str) -> IResult<&str, OffsetValue> { Ok((rem_input, offset_value)) } -pub fn parse_value(input: &str) -> IResult<&str, ValueAddress> { +pub(crate) fn parse_value(input: &str) -> IResult<&str, ValueAddress> { let (rem_input, (dereference, second_arg, fst_offset, snd_offset)) = tuple(( outer_brackets, take_cast_first_arg, @@ -216,10 +194,15 @@ pub fn parse_value(input: &str) -> IResult<&str, ValueAddress> { /// work inside the `nom::sequence::delimited()` parser. /// /// # Basic usage -/// ``` +/// ```no_run /// use nom::bytes::complete::tag; /// use nom::sequence::delimited; -/// use cairo_take_until_unbalanced::take_until_unbalanced; +/// # use nom::IResult; +/// +/// # fn take_until_unbalanced( +/// # opening_bracket: char, +/// # closing_bracket: char, +/// # ) -> impl Fn(&str) -> IResult<&str, &str> { |_| Ok(("", "")) } /// /// let mut parser = delimited(tag("<"), take_until_unbalanced('<', '>'), tag(">")); /// assert_eq!(parser("<inside>abc"), Ok(("abc", "inside"))); @@ -229,7 +212,7 @@ pub fn parse_value(input: &str) -> IResult<&str, ValueAddress> { /// very similar to `nom::bytes::complete::take_until(">")`, except it also takes nested brackets. /// NOTE: trimmed down from https://docs.rs/parse-hyperlinks to fix bugs. The project itself seems /// abandonned. -pub fn take_until_unbalanced( +fn take_until_unbalanced( opening_bracket: char, closing_bracket: char, ) -> impl Fn(&str) -> IResult<&str, &str> { diff --git a/vm/src/serde/mod.rs b/vm/src/serde/mod.rs index 81ea65b5da..43c91a2093 100644 --- a/vm/src/serde/mod.rs +++ b/vm/src/serde/mod.rs @@ -1,2 +1,2 @@ pub mod deserialize_program; -pub mod deserialize_utils; +mod deserialize_utils; diff --git a/vm/src/vm/mod.rs b/vm/src/vm/mod.rs index 4fb3779f25..69c524736b 100644 --- a/vm/src/vm/mod.rs +++ b/vm/src/vm/mod.rs @@ -7,6 +7,6 @@ pub mod trace; pub mod vm_core; pub mod vm_memory; -#[cfg(any(feature = "hooks"))] +#[cfg(feature = "hooks")] #[cfg_attr(docsrs, doc(cfg(feature = "hooks")))] pub mod hooks;