Struct EntryBuilder 

pub struct EntryBuilder { /* private fields */ }

A builder for creating Entry instances.

EntryBuilder allows mutable construction of an entry’s content. Once finalized with the build() method, it produces an immutable Entry with a deterministically calculated ID.

Parameter Type Efficiency

The builder uses impl Into<ID> and impl Into<RawData> for parameters, allowing you to pass string literals, &str, String, or the appropriate types without unnecessary conversions:

// Efficient - no unnecessary .to_string() calls needed
let entry = Entry::builder("root_id")
    .add_parent("parent1")
    .set_subtree_data("users", "user_data")
    .build();

Mutable Construction

The builder provides two patterns for construction:

1. Ownership chaining: Each method returns self for chained calls.

   let entry = Entry::builder(root_id)
       .set_subtree_data("users".to_string(), "user_data".to_string())
       .add_parent("parent_id".to_string())
       .build();

2. Mutable reference: Methods ending in _mut modify the builder in place.

   let mut builder = Entry::builder(root_id);
   builder.set_subtree_data_mut("users".to_string(), "user_data".to_string());
   builder.add_parent_mut("parent_id".to_string());
   let entry = builder.build();

Example

use eidetica::Entry;

// Create a builder for a regular entry
let entry = Entry::builder("root_id")
    .add_parent("parent1")
    .set_subtree_data("users", "user_data")
    .build();

// Create a builder for a top-level root entry
let root_entry = Entry::root_builder()
    .set_subtree_data("users", "initial_user_data")
    .build();

Implementations

impl EntryBuilder

pub fn new(root: impl Into<ID>) -> Self

Creates a new EntryBuilder for an entry associated with a specific tree root.

Arguments

• root - The ID of the root Entry of the tree this entry will belong to.

Note: It’s generally preferred to use the static Entry::builder() method instead of calling this constructor directly.

pub fn new_top_level() -> Self

Creates a new EntryBuilder for a top-level (root) entry for a new tree.

Root entries have an empty string as their root ID and include a special ROOT subtree marker. This method is typically used when creating a new tree.

Note: It’s generally preferred to use the static Entry::root_builder() method instead of calling this constructor directly.

pub fn set_sig(self, sig: SigInfo) -> Self

Set the authentication information for this entry.

Arguments

• auth - The authentication information including key ID and optional signature

pub fn set_sig_mut(&mut self, sig: SigInfo) -> &mut Self

Mutable reference version of set_auth. Set the authentication information for this entry.

Arguments

• auth - The authentication information including key ID and optional signature

pub fn subtrees(&self) -> Vec<String>

Get the names of all subtrees this entry builder contains data for. The names are returned in alphabetical order.

pub fn data(&self, subtree_name: impl AsRef<str>) -> Result<&RawData>

Get the RawData for a specific named subtree within this entry builder.

Returns an error if the subtree is not found or if the subtree exists but has no data (None).

pub fn parents(&self) -> Result<Vec<ID>>

Get the IDs of the parent entries for the main tree. The parent IDs are returned in alphabetical order.

pub fn subtree_parents(&self, subtree_name: impl AsRef<str>) -> Result<Vec<ID>>

Get the IDs of the parent entries specific to a named subtree’s history. The parent IDs are returned in alphabetical order.

pub fn set_subtree_data( self, name: impl Into<String>, data: impl Into<RawData>, ) -> Self

Sets data for a named subtree, creating it if it doesn’t exist. The list of subtrees will be sorted by name when build() is called.

Arguments

• name - The name of the subtree (e.g., “users”, “products”).
• data - RawData (serialized string) specific to this entry for the named subtree.

pub fn set_subtree_data_mut( &mut self, name: impl Into<String>, data: impl Into<RawData>, ) -> &mut Self

Mutable reference version of set_subtree_data. Sets data for a named subtree, creating it if it doesn’t exist. The list of subtrees will be sorted by name when build() is called.

Arguments

• name - The name of the subtree (e.g., “users”, “products”).
• data - RawData (serialized string) specific to this entry for the named subtree.

pub fn remove_empty_subtrees(self) -> Result<Self>

Removes subtrees that have empty data.

This removes subtrees with Some("") (actual empty data) and subtrees with None (no data changes) UNLESS the subtree is referenced in the _index subtree’s data.

When _index is updated for a subtree, that subtree must appear in the Entry. This is marked by having None data and being referenced in _index.

This is useful for cleaning up entries before building.

Errors

Returns an error if the _index subtree data exists but cannot be deserialized.

pub fn remove_empty_subtrees_mut(&mut self) -> Result<&mut Self>

Mutable reference version of remove_empty_subtrees.

Removes subtrees with Some("") and subtrees with None unless referenced in _index.

Errors

Returns an error if the _index subtree data exists but cannot be deserialized.

pub fn set_root(self, root: impl Into<String>) -> Self

Set the root ID for this entry.

Arguments

• root - The ID of the root Entry of the tree this entry will belong to.

Returns

A mutable reference to self for method chaining.

pub fn set_root_mut(&mut self, root: impl Into<String>) -> &mut Self

Mutable reference version of set_root. Set the root ID for this entry.

Arguments

• root - The ID of the root Entry of the tree this entry will belong to.

Returns

A mutable reference to self for method chaining.

pub fn set_parents(self, parents: Vec<ID>) -> Self

Set the parent IDs for the main tree history. The provided vector will be sorted alphabetically during the build() process.

pub fn set_parents_mut(&mut self, parents: Vec<ID>) -> &mut Self

Mutable reference version of set_parents. Set the parent IDs for the main tree history. The provided vector will be sorted alphabetically during the build() process.

pub fn add_parent(self, parent_id: impl Into<String>) -> Self

Add a single parent ID to the main tree history. Parents will be sorted and duplicates handled during the build() process.

pub fn add_parent_mut(&mut self, parent_id: impl Into<String>) -> &mut Self

Mutable reference version of add_parent. Add a single parent ID to the main tree history. Parents will be sorted and duplicates handled during the build() process.

pub fn get_parents(&self) -> Option<&Vec<ID>>

Get a reference to the current parent IDs for the main tree history.

pub fn set_subtree_parents( self, subtree_name: impl Into<String>, parents: Vec<ID>, ) -> Self

Set the parent IDs for a specific named subtree’s history. The provided vector will be sorted alphabetically and de-duplicated during the build() process. If the subtree does not exist, it will be created with empty data (“{}”). The list of subtrees will be sorted by name when build() is called.

pub fn set_subtree_parents_mut( &mut self, subtree_name: impl Into<String>, parents: Vec<ID>, ) -> &mut Self

Mutable reference version of set_subtree_parents. Set the parent IDs for a specific named subtree’s history. The provided vector will be sorted alphabetically and de-duplicated during the build() process. If the subtree does not exist, it will be created with no data (None). The list of subtrees will be sorted by name when build() is called.

pub fn add_subtree_parent( self, subtree_name: impl Into<String>, parent_id: impl Into<String>, ) -> Self

Add a single parent ID to a specific named subtree’s history. If the subtree does not exist, it will be created with no data (None). Parent IDs will be sorted and de-duplicated during the build() process. The list of subtrees will be sorted by name when build() is called.

pub fn add_subtree_parent_mut( &mut self, subtree_name: impl Into<String>, parent_id: impl Into<String>, ) -> &mut Self

Mutable reference version of add_subtree_parent. Add a single parent ID to a specific named subtree’s history. If the subtree does not exist, it will be created with no data (None). Parent IDs will be sorted and de-duplicated during the build() process. The list of subtrees will be sorted by name when build() is called.

pub fn set_metadata(self, metadata: impl Into<String>) -> Self

Set the metadata for this entry’s tree node.

Metadata is optional information attached to an entry that is not part of the main data model and is not merged between entries. It’s used primarily for improving efficiency of operations and for experimentation.

For example, metadata can contain references to the current tips of the settings subtree, allowing for efficient verification in sparse checkout scenarios.

Arguments

• metadata - RawData (serialized string) for the main tree node metadata.

Returns

Self for method chaining.

pub fn set_metadata_mut(&mut self, metadata: impl Into<String>) -> &mut Self

Mutable reference version of set_metadata. Set the metadata for this entry’s tree node.

Metadata is optional information attached to an entry that is not part of the main data model and is not merged between entries. It’s used primarily for improving efficiency of operations and for experimentation.

For example, metadata can contain references to the current tips of the settings subtree, allowing for efficient verification in sparse checkout scenarios.

Arguments

• metadata - RawData (serialized string) for the main tree node metadata.

Returns

A mutable reference to self for method chaining.

pub fn metadata(&self) -> Option<&RawData>

Get the current metadata value for this entry builder.

Metadata is optional information attached to an entry that is not part of the main data model and is not merged between entries. It’s used primarily for improving efficiency of operations and for experimentation.

Returns

Returns Some(&RawData) containing the serialized metadata if present, or None if no metadata has been set.

Example

let builder = Entry::builder("root_id");
assert!(builder.metadata().is_none());

let builder = builder.set_metadata(r#"{"custom": "data"}"#);
assert!(builder.metadata().is_some());

pub fn set_height(self, height: u64) -> Self

Set the height for this entry in the main tree DAG.

Arguments

• height - The height value for this entry

pub fn set_height_mut(&mut self, height: u64) -> &mut Self

Mutable reference version of set_height.

pub fn set_subtree_height( self, subtree_name: impl Into<String>, height: Option<u64>, ) -> Self

Set the height for this entry in a specific subtree’s DAG.

If the subtree does not exist, it will be created with no data (None).

Arguments

• subtree_name - The name of the subtree
• height - The height value for this entry in the subtree

pub fn set_subtree_height_mut( &mut self, subtree_name: impl Into<String>, height: Option<u64>, ) -> &mut Self

Mutable reference version of set_subtree_height.

pub fn build(self) -> Result<Entry>

Build and return the final immutable Entry.

This method:

1. Sorts all parent lists in both the main tree and subtrees
2. Sorts the subtrees list by name
3. Removes any empty subtrees
4. Creates the immutable Entry
5. Validates the entry structure
6. Returns the validated entry or an error

After calling this method, the builder is consumed and cannot be used again. The returned Entry is immutable and its parts cannot be modified.

Returns

• Ok(Entry) if the entry is structurally valid
• Err(crate::Error) if the entry fails validation (e.g., root entry with parents)

Trait Implementations

impl Clone for EntryBuilder

fn clone(&self) -> EntryBuilder

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EntryBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.