From 0cd7aa376a3bfcdc46e0cb1bc63269197274e294 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1?= <47506558+MegaRedHand@users.noreply.github.com> Date: Fri, 14 Jul 2023 11:46:27 -0300 Subject: [PATCH 1/9] Document Program deserialization modules --- vm/src/serde/deserialize_program.rs | 8 ++++++++ vm/src/serde/deserialize_utils.rs | 15 ++++++++++----- 2 files changed, 18 insertions(+), 5 deletions(-) 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..c4bb6d48a2 100644 --- a/vm/src/serde/deserialize_utils.rs +++ b/vm/src/serde/deserialize_utils.rs @@ -1,3 +1,10 @@ +//! # Deserialization utils +//! +//! This module contains some helper functions used in [`Program`](crate::types::program::Program) deserialization. +//! Namely, [`maybe_add_padding`] and [`take_until_unbalanced`]. +//! +//! See [the docs](/docs/references_parsing/README.md) for context and grammar explanation. + use crate::stdlib::{fmt, num::ParseIntError, prelude::*, str::FromStr}; use crate::{ @@ -55,11 +62,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. From ce28cfeec9245b84a00850270d148d0af7e69079 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1?= <47506558+MegaRedHand@users.noreply.github.com> Date: Fri, 14 Jul 2023 12:46:00 -0300 Subject: [PATCH 2/9] Update lib.rs module documentation --- vm/src/lib.rs | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/vm/src/lib.rs b/vm/src/lib.rs index c6387994c4..e9ffd371f6 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. +//! - `hooks`: Enable [`Hooks`](vm::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`] 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)] From 6bf3e45786360180d371640fa17b9df8973e2352 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1?= <47506558+MegaRedHand@users.noreply.github.com> Date: Fri, 14 Jul 2023 12:50:55 -0300 Subject: [PATCH 3/9] Update changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0c67fa2113..3d0c3562be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ #### Upcoming Changes +* docs: improve crate documentation [#1334](https://github.com/lambdaclass/cairo-vm/pull/1334) + * feat: add `arbitrary` feature to enable arbitrary derive in `Program` and `CairoRunConfig` * feat(fuzzing): add `arbitrary` feature to enable arbitrary derive in `Program` and `CairoRunConfig` [#1306](https://github.com/lambdaclass/cairo-vm/pull/1306) [#1330](https://github.com/lambdaclass/cairo-vm/pull/1330) From 45cea78d5a07bd844dd9ddb0813c2436e55d88d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1?= <47506558+MegaRedHand@users.noreply.github.com> Date: Mon, 17 Jul 2023 13:12:12 -0300 Subject: [PATCH 4/9] Make deserialize utils private --- vm/src/serde/deserialize_utils.rs | 37 +++++-------------------------- vm/src/serde/mod.rs | 2 +- 2 files changed, 6 insertions(+), 33 deletions(-) diff --git a/vm/src/serde/deserialize_utils.rs b/vm/src/serde/deserialize_utils.rs index c4bb6d48a2..e6d753917d 100644 --- a/vm/src/serde/deserialize_utils.rs +++ b/vm/src/serde/deserialize_utils.rs @@ -5,13 +5,12 @@ //! //! See [the docs](/docs/references_parsing/README.md) for context and grammar explanation. -use crate::stdlib::{fmt, num::ParseIntError, prelude::*, str::FromStr}; - +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::{ @@ -26,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; @@ -167,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, @@ -234,7 +207,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( +pub(crate) 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; From f3c5cd9e13b4cf3c4fb15b50031c6611566bb87d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1?= <47506558+MegaRedHand@users.noreply.github.com> Date: Mon, 17 Jul 2023 13:15:25 -0300 Subject: [PATCH 5/9] Update fuzzer's Cargo.lock --- fuzzer/Cargo.lock | 3 +++ 1 file changed, 3 insertions(+) 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", From 8f9b755c810bbfce5b40bfaa5b855627f5ee51e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1?= <47506558+MegaRedHand@users.noreply.github.com> Date: Mon, 17 Jul 2023 13:16:25 -0300 Subject: [PATCH 6/9] Make take_until_unbalanced private --- vm/src/serde/deserialize_utils.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vm/src/serde/deserialize_utils.rs b/vm/src/serde/deserialize_utils.rs index e6d753917d..81f8c89674 100644 --- a/vm/src/serde/deserialize_utils.rs +++ b/vm/src/serde/deserialize_utils.rs @@ -207,7 +207,7 @@ pub(crate) 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(crate) fn take_until_unbalanced( +fn take_until_unbalanced( opening_bracket: char, closing_bracket: char, ) -> impl Fn(&str) -> IResult<&str, &str> { From f7f4e425196cfb898e408d5dd78f714053c2a181 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1?= <47506558+MegaRedHand@users.noreply.github.com> Date: Mon, 17 Jul 2023 13:34:50 -0300 Subject: [PATCH 7/9] Update docs --- vm/src/serde/deserialize_utils.rs | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/vm/src/serde/deserialize_utils.rs b/vm/src/serde/deserialize_utils.rs index 81f8c89674..5a90ec863d 100644 --- a/vm/src/serde/deserialize_utils.rs +++ b/vm/src/serde/deserialize_utils.rs @@ -1,7 +1,7 @@ //! # Deserialization utils //! //! This module contains some helper functions used in [`Program`](crate::types::program::Program) deserialization. -//! Namely, [`maybe_add_padding`] and [`take_until_unbalanced`]. +//! Namely, [`maybe_add_padding`] and [`parse_value`]. //! //! See [the docs](/docs/references_parsing/README.md) for context and grammar explanation. @@ -194,10 +194,15 @@ pub(crate) 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"))); From 322c368c86e722915a3be06ae9d5ffc7e39fdf50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1?= <47506558+MegaRedHand@users.noreply.github.com> Date: Mon, 17 Jul 2023 13:47:10 -0300 Subject: [PATCH 8/9] Fix links --- vm/src/lib.rs | 6 +++--- vm/src/vm/mod.rs | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/vm/src/lib.rs b/vm/src/lib.rs index e9ffd371f6..23205cc8d2 100644 --- a/vm/src/lib.rs +++ b/vm/src/lib.rs @@ -3,11 +3,11 @@ //! ## 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. +//! - `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. +//! - `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`] for some structs. 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))] 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; From 825d3797a3d0464cd2043257f422018fd051ebfc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1?= <47506558+MegaRedHand@users.noreply.github.com> Date: Mon, 17 Jul 2023 15:17:46 -0300 Subject: [PATCH 9/9] Update changelog entry --- CHANGELOG.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e6533b7ffa..a9ff054a3e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,13 @@ #### Upcoming Changes -* docs: improve crate documentation [#1334](https://github.com/lambdaclass/cairo-vm/pull/1334) +* 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 * perf: changed `ok_or` usage for `ok_or_else` in expensive cases [#1332](https://github.com/lambdaclass/cairo-vm/pull/1332)