======================== CODE SNIPPETS ======================== TITLE: Installing Molecule Schema Compiler (Shell) DESCRIPTION: Installs the official Molecule schema compiler and code generator (`moleculec`) using the Cargo package manager, ensuring locked dependencies are used. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/README.md#_snippet_2 LANGUAGE: Shell CODE: ``` cargo install moleculec --locked ``` ---------------------------------------- TITLE: Start Fuzzer with Make (Shell) DESCRIPTION: Executes the 'start-fuzzer' target in the Makefile to run the project's fuzzer. This command initiates the fuzzing process as configured in the Makefile. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/fuzzing/c/README.md#_snippet_1 LANGUAGE: Shell CODE: ``` make start-fuzzer ``` ---------------------------------------- TITLE: Getting Help for Molecule Compiler (Shell) DESCRIPTION: Displays the help message and usage information for the `moleculec` command-line tool. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/README.md#_snippet_4 LANGUAGE: Shell CODE: ``` moleculec --help ``` ---------------------------------------- TITLE: Example Molecule Schema for Compatibility (mol) DESCRIPTION: This Molecule schema example demonstrates how compatible reading works. An older schema (`Old`) can read data generated by a newer schema (`New`) that has added fields, but not removed ones. The `from_compatible_slice` API is used for this purpose. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/molecule_api.md#_snippet_1 LANGUAGE: mol CODE: ``` vector Inner ; table Old { a: Inner, b: Inner, } table New { a: Inner, b: Inner, c: Inner, } ``` ---------------------------------------- TITLE: Defining Line Comments in Molecule DESCRIPTION: Demonstrates the syntax for single-line comments in the Molecule Schema Language, starting with `//`. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md#_snippet_0 LANGUAGE: molecule CODE: ``` // This is a line comment ``` ---------------------------------------- TITLE: Run Fuzz Tests with Cargo Fuzz (shell) DESCRIPTION: Executes the specified fuzz test using the `cargo fuzz` tool. This command starts the fuzzing process for the target named 'data'. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/fuzzing/rust/README.md#_snippet_0 LANGUAGE: shell CODE: ``` cargo fuzz run data ``` ---------------------------------------- TITLE: Serialize BytesVec [0x1234] - Hex Bytes DESCRIPTION: Example serialization of a Molecule vector `BytesVec` containing a single `Bytes` item `0x1234`. Shows the full size, offset, and item data. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/encoding_spec.md#_snippet_1 LANGUAGE: Hex Bytes CODE: ``` # the full size is 14 bytes 0e 00 00 00 # one offset 08 00 00 00 # one item 02 00 00 00 12 34 ``` ---------------------------------------- TITLE: Serialize MixedType Table - Hex Bytes DESCRIPTION: Example serialization of a Molecule table `MixedType` with fields of different types (`Bytes`, `byte`, `Uint32`, `Byte3`). Shows the full size, offsets for each field, and the serialized data for each field. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/encoding_spec.md#_snippet_3 LANGUAGE: Hex Bytes CODE: ``` # the full size is 43 (0x2b) bytes 2b 00 00 00 # five offsets (20 bytes in total) 18 00 00 00, 1c 00 00 00, 1d 00 00 00, 21 00 00 00, 24 00 00 00 # five items (19 bytes in total) 00 00 00 00 ab 23 01 00 00 45 67 89 03 00 00 00, ab cd ef ``` ---------------------------------------- TITLE: Serialize BytesVec Multiple Items - Hex Bytes DESCRIPTION: Example serialization of a Molecule vector `BytesVec` containing multiple `Bytes` items of varying lengths. Shows the full size, offsets for each item, and the serialized data for each item. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/encoding_spec.md#_snippet_2 LANGUAGE: Hex Bytes CODE: ``` # the full size is 52 (0x34) bytes 34 00 00 00 # five offsets (20 bytes in total) 18 00 00 00, 1e 00 00 00, 22 00 00 00, 28 00 00 00, 2d 00 00 00 # five items (28 bytes in total) 02 00 00 00, 12 34 00 00 00 00, 02 00 00 00, 05 67 01 00 00 00, 89 03 00 00 00, ab cd ef ``` ---------------------------------------- TITLE: Serialize BytesVecOpt Some([0x]) - Hex Bytes DESCRIPTION: Example serialization of a Molecule option type `BytesVecOpt` containing `Some` with a `BytesVec` that has a single empty `Bytes` item (`[0x]`). Shows the serialized bytes of the inner `BytesVec`. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/encoding_spec.md#_snippet_4 LANGUAGE: Hex Bytes CODE: ``` # the full size of BytesVec is 12 bytes 0c 00 00 00 # the offset of Bytes 08 00 00 00 # the length of Bytes 00 00 00 00 ``` ---------------------------------------- TITLE: Serialize HybridBytes Union (BytesVec) - Hex Bytes DESCRIPTION: Example serialization of a Molecule union type `HybridBytes` containing a `BytesVec` with two `Bytes` items (`[0x123, 0x456]`). Shows the item type ID for `BytesVec` followed by the serialized bytes of the inner `BytesVec`. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/encoding_spec.md#_snippet_5 LANGUAGE: Hex Bytes CODE: ``` # Item Type Id 02 00 00 00 # the full size of BytesVec is 24 bytes 18 00 00 00 # two offsets of BytesVec (8 bytes in total) 0c 00 00 00, 12 00 00 00, # two Bytes (12 bytes in total) 02 00 00 00, 01 23 02 00 00 00, 04 56 ``` ---------------------------------------- TITLE: Serialize HybridBytes Union (BytesVecOpt) - Hex Bytes DESCRIPTION: Example serialization of a Molecule union type `HybridBytes` containing a `BytesVecOpt` with `Some` containing a `BytesVec` with two `Bytes` items (`[0x123, 0x456]`). Shows the item type ID for `BytesVecOpt` followed by the serialized bytes of the inner `BytesVecOpt` (which is the serialized `BytesVec`). SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/encoding_spec.md#_snippet_6 LANGUAGE: Hex Bytes CODE: ``` # Item Type Id 03 00 00 00 # the full size of BytesVec is 24 bytes 18 00 00 00 # two offsets of BytesVec (8 bytes in total) 0c 00 00 00, 12 00 00 00, # two Bytes (12 bytes in total) 02 00 00 00, 01 23 02 00 00 00, 04 56 ``` ---------------------------------------- TITLE: Build Project with Make (Shell) DESCRIPTION: Executes the default 'all' target in the Makefile to build the project. This command compiles the necessary components based on the rules defined in the Makefile. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/fuzzing/c/README.md#_snippet_0 LANGUAGE: Shell CODE: ``` make all ``` ---------------------------------------- TITLE: Importing Types in Molecule DESCRIPTION: Demonstrates the syntax for importing type definitions from other Molecule schema files using the `import` keyword. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md#_snippet_8 LANGUAGE: molecule CODE: ``` import ../library/common_types; ``` ---------------------------------------- TITLE: Configuring Molecule 0.7 for CKB Scripts (TOML) DESCRIPTION: Configures the Molecule dependency in a Cargo.toml file for use in CKB scripts, disabling default features to ensure a `no-std` environment. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/README.md#_snippet_0 LANGUAGE: TOML CODE: ``` molecule = { version = "0.7", default-features = false } ``` ---------------------------------------- TITLE: Generating Code with Molecule Compiler (Shell) DESCRIPTION: Uses the `moleculec` command-line tool to generate code from a Molecule schema file for a specified target programming language. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/README.md#_snippet_3 LANGUAGE: Shell CODE: ``` moleculec --language --schema-file ``` ---------------------------------------- TITLE: Configuring Molecule 0.8+ for CKB Scripts (TOML) DESCRIPTION: Configures the Molecule dependency in a Cargo.toml file for versions 0.8 and later, disabling default features and explicitly enabling the `bytes_vec` feature for compatibility in CKB scripts. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/README.md#_snippet_1 LANGUAGE: TOML CODE: ``` molecule = { version = "0.8.0", default-features = false, features = ["bytes_vec"] } ``` ---------------------------------------- TITLE: Defining Block Comments in Molecule DESCRIPTION: Shows the syntax for multi-line block comments in Molecule, enclosed within `/*` and `*/`. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md#_snippet_1 LANGUAGE: molecule CODE: ``` /* This is a block comment */ ``` ---------------------------------------- TITLE: Generate Fuzz Coverage Report with Cargo Fuzz and Cargo Cov (shell) DESCRIPTION: Generates a code coverage report for the fuzz tests. The first command collects coverage data, and the second command uses `cargo cov` to format this data into an HTML report. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/fuzzing/rust/README.md#_snippet_1 LANGUAGE: shell CODE: ``` cargo fuzz coverage data cargo cov -- show target/x86_64-unknown-linux-gnu/coverage/x86_64-unknown-linux-gnu/release/data \ --format=html \ -instr-profile=fuzz/coverage/data/coverage.profdata \ > data.html ``` ---------------------------------------- TITLE: Defining Array Type in Molecule DESCRIPTION: Illustrates the syntax for defining an array type in Molecule, specifying the item type and a fixed size `N`. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md#_snippet_2 LANGUAGE: molecule CODE: ``` array ArrayName [ItemType; N]; ``` ---------------------------------------- TITLE: Defining Table Type in Molecule DESCRIPTION: Illustrates the syntax for defining a table type in Molecule, similar to a struct with named and typed fields, but potentially with different serialization characteristics (often used for variable-size fields). SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md#_snippet_5 LANGUAGE: molecule CODE: ``` table TableName { field_name_1: FieldType1, field_name_2: FieldType2, field_name_3: FieldType3, } ``` ---------------------------------------- TITLE: Defining the Builder Trait in Rust DESCRIPTION: The `Builder` trait is used to construct and serialize Molecule structures using the builder pattern. It allows setting fields and then converting the builder into the final serialized `Entity` structure via the `build` method, or writing directly to an I/O writer. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/molecule_api.md#_snippet_3 LANGUAGE: Rust CODE: ``` pub trait Builder: Default { type Entity: Entity; const NAME: &'static str; fn expected_length(&self) -> usize; fn write(&self, writer: &mut W) -> io::Result<()>; fn build(&self) -> Self::Entity; } ``` ---------------------------------------- TITLE: Defining Option Type in Molecule DESCRIPTION: Provides the syntax for defining an option type in Molecule, which represents a value that may or may not be present, containing an optional item type. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md#_snippet_6 LANGUAGE: molecule CODE: ``` option OptionName (ItemType); ``` ---------------------------------------- TITLE: Defining Struct Type in Molecule DESCRIPTION: Provides the syntax for defining a struct type in Molecule, which is a composite type with named and typed fields. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md#_snippet_3 LANGUAGE: molecule CODE: ``` struct StructName { field_name_1: FieldType1, field_name_2: FieldType2, field_name_3: FieldType3, } ``` ---------------------------------------- TITLE: Defining the Reader Trait in Rust DESCRIPTION: The `Reader` trait is generated for each Molecule structure in Rust. It provides methods for accessing the internal fields of a structure and includes static methods for verifying data slices, supporting both strict and compatible verification. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/molecule_api.md#_snippet_2 LANGUAGE: Rust CODE: ``` pub trait Reader<'r>: Sized + fmt::Debug + Clone + Copy { type Entity: Entity; const NAME: &'static str; fn verify(slice: &[u8], compatible: bool) -> VerificationResult<()>; fn new_unchecked(slice: &'r [u8]) -> Self; fn as_slice(&self) -> &'r [u8]; fn from_slice(slice: &'r [u8]) -> VerificationResult { Self::verify(slice, false).map(|_| Self::new_unchecked(slice)) } fn from_compatible_slice(slice: &'r [u8]) -> VerificationResult { Self::verify(slice, true).map(|_| Self::new_unchecked(slice)) } fn to_entity(&self) -> Self::Entity; } ``` ---------------------------------------- TITLE: Defining Union Type in Molecule DESCRIPTION: Shows the syntax for defining a union type in Molecule, which can hold a value of one of several specified item types. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md#_snippet_7 LANGUAGE: molecule CODE: ``` union UnionName { ItemType1, ItemType2, ItemType3, } ``` ---------------------------------------- TITLE: Serializing Array of Bytes (Byte3) - Byte Sequence DESCRIPTION: Demonstrates the serialization of a fixed-size array `Byte3` containing three byte values (01, 02, 03). The bytes are stored consecutively in the serialized output. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/encoding_spec.md#_snippet_0 LANGUAGE: Byte Sequence CODE: ``` 01 02 03 ``` ---------------------------------------- TITLE: Defining Vector Type in Molecule DESCRIPTION: Shows the syntax for defining a vector type in Molecule, which is a composite type with a single item type and variable size. SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/schema_language.md#_snippet_4 LANGUAGE: molecule CODE: ``` vector VectorName ; ``` ---------------------------------------- TITLE: Defining the Entity Trait in Rust DESCRIPTION: The `Entity` trait represents a serialized data structure in Molecule's Rust implementation. It provides methods for creating, accessing, and verifying data, including handling compatible schema versions. It's important to distinguish between `as_slice` (complete data) and `raw_data` (data without header). SOURCE: https://github.com/nervosnetwork/molecule/blob/master/docs/molecule_api.md#_snippet_0 LANGUAGE: Rust CODE: ``` pub trait Entity: fmt::Debug + Default + Clone { type Builder: Builder; const NAME: &'static str; fn new_unchecked(data: Bytes) -> Self; fn as_bytes(&self) -> Bytes; fn as_slice(&self) -> &[u8]; fn from_slice(slice: &[u8]) -> VerificationResult; fn from_compatible_slice(slice: &[u8]) -> VerificationResult; fn new_builder() -> Self::Builder; fn as_builder(self) -> Self::Builder; } ```