Struct Automerge 

pub struct Automerge { /* private fields */ }

An automerge document which does not manage transactions for you.

Creating, loading, merging and forking documents

A new document can be created with Self::new(), which will create a document with a random ActorId. Existing documents can be loaded with Self::load(), or Self::load_with().

If you have two documents and you want to merge the changes from one into the other you can use Self::merge() or Self::merge_and_log_patches().

If you have a document you want to split into two concurrent threads of execution you can use Self::fork(). If you want to split a document from ealier in its history you can use Self::fork_at().

Reading values

Self implements ReadDoc, which provides methods for reading values from the document.

Modifying a document (Transactions)

Automerge provides an interface for viewing and modifying automerge documents which does not manage transactions for you. To create changes you use either Automerge::transaction() or Automerge::transact() (or the _with variants).

Sync

This type implements crate::sync::SyncDoc

Implementations

impl Automerge

pub fn new() -> Self

Create a new document with a random actor id.

pub fn init_from_hydrate(&mut self, value: &Map) -> Result<(), AutomergeError>

Overwrite the keys of the root object with the values from value

This is useful to initialize an empty document with a large initial value. Note that existing keys which are not in value are left as is

pub fn new_with_encoding(encoding: TextEncoding) -> Self

pub fn is_empty(&self) -> bool

Whether this document has any operations

pub fn with_actor(self, actor: ActorId) -> Self

Set the actor id for this document.

pub fn set_actor(&mut self, actor: ActorId) -> &mut Self

Set the actor id for this document.

pub fn get_actor(&self) -> &ActorId

Get the current actor id of this document.

pub fn transaction(&mut self) -> Transaction<'_>

Start a transaction.

pub fn transaction_log_patches( &mut self, patch_log: PatchLog, ) -> Transaction<'_>

Start a transaction which records changes in a PatchLog

pub fn transaction_at( &mut self, patch_log: PatchLog, heads: &[ChangeHash], ) -> Transaction<'_>

Start a transaction isolated at a given heads

pub fn into_transaction( self, patch_log: Option<PatchLog>, heads: Option<&[ChangeHash]>, ) -> OwnedTransaction

Start a transaction that owns the document, consuming self.

This is useful when the transaction must be 'static (e.g. storing across an FFI boundary or in a struct that requires 'static). The document is returned when the transaction is committed or rolled back.

Arguments

• patch_log - An optional PatchLog to log the changes in this transaction to
• heads - An optional set of heads to isolate this transaction at, or None to use the current heads of the document

pub fn transact<F, O, E>(&mut self, f: F) -> Result<O, E>

where F: FnOnce(&mut Transaction<'_>) -> Result<O, E>,

Run a transaction on this document in a closure, automatically handling commit or rollback afterwards.

pub fn transact_with<F, O, E, C>(&mut self, c: C, f: F) -> Result<O, E>

where F: FnOnce(&mut Transaction<'_>) -> Result<O, E>, C: FnOnce(&O) -> CommitOptions,

Like Self::transact() but with a function for generating the commit options.

pub fn transact_and_log_patches<F, O, E>(&mut self, f: F) -> Result<O, E>

where F: FnOnce(&mut Transaction<'_>) -> Result<O, E>,

Run a transaction on this document in a closure, collecting patches, automatically handling commit or rollback afterwards.

The collected patches are available in the return value of Transaction::commit()

pub fn transact_and_log_patches_with<F, O, E, C>( &mut self, c: C, f: F, ) -> Result<O, E>

where F: FnOnce(&mut Transaction<'_>) -> Result<O, E>, C: FnOnce(&O) -> CommitOptions,

Like Self::transact_and_log_patches() but with a function for generating the commit options

pub fn empty_commit(&mut self, opts: CommitOptions) -> ChangeHash

Generate an empty change

The main reason to do this is if you want to create a “merge commit”, which is a change that has all the current heads of the document as dependencies.

pub fn fork(&self) -> Self

Fork this document at the current point for use by a different actor.

This will create a new actor ID for the forked document

pub fn fork_at(&self, heads: &[ChangeHash]) -> Result<Self, AutomergeError>

Fork this document at the given heads

This will create a new actor ID for the forked document

pub fn diff_opset(&self, other: &Self) -> Result<(), AutomergeError>

pub fn load(data: &[u8]) -> Result<Self, AutomergeError>

Load a document.

pub fn load_unverified_heads(data: &[u8]) -> Result<Self, AutomergeError>

Load a document without verifying the head hashes

This is useful for debugging as it allows you to examine a corrupted document.

pub fn load_with( data: &[u8], on_error: OnPartialLoad, mode: VerificationMode, patch_log: &mut PatchLog, ) -> Result<Self, AutomergeError>

👎Deprecated since 0.5.2:

Use load_with_options instead

Load a document, with options

Arguments

• data - The data to load
• on_error - What to do if the document is only partially loaded. This can happen if some prefix of data contains valid data.
• mode - Whether to verify the head hashes after loading
• patch_log - A PatchLog to log the changes required to materialize the current state of the document once loaded

pub fn load_with_options( data: &[u8], options: LoadOptions<'_>, ) -> Result<Self, AutomergeError>

Load a document, with options

Arguments

• data - The data to load
• options - The options to use when loading

pub fn make_patches(&self, patch_log: &mut PatchLog) -> Vec<Patch>

Create the patches from a PatchLog

See the documentation for PatchLog for more details on this

pub fn current_state(&self) -> Vec<Patch>

Get a set of Patches which materialize the current state of the document

This is a convienence method for doc.diff(&[], current_heads)

pub fn load_incremental(&mut self, data: &[u8]) -> Result<usize, AutomergeError>

Load an incremental save of a document.

Unlike Self::load() this imports changes into an existing document. It will work with both the output of Self::save() and Self::save_after()

The return value is the number of ops which were applied, this is not useful and will change in future.

pub fn load_incremental_log_patches( &mut self, data: &[u8], patch_log: &mut PatchLog, ) -> Result<usize, AutomergeError>

Like Self::load_incremental() but log the changes to the current state of the document to PatchLog

pub fn apply_changes( &mut self, changes: impl IntoIterator<Item = Change> + Clone, ) -> Result<(), AutomergeError>

Apply changes to this document.

This is idempotent in the sense that if a change has already been applied it will be ignored.

pub fn apply_changes_log_patches<I: IntoIterator<Item = Change> + Clone>( &mut self, changes: I, patch_log: &mut PatchLog, ) -> Result<(), AutomergeError>

Like Self::apply_changes() but log the resulting changes to the current state of the document to patch_log

pub fn merge( &mut self, other: &mut Self, ) -> Result<Vec<ChangeHash>, AutomergeError>

Takes all the changes in other which are not in self and applies them

pub fn merge_and_log_patches( &mut self, other: &mut Self, patch_log: &mut PatchLog, ) -> Result<Vec<ChangeHash>, AutomergeError>

Takes all the changes in other which are not in self and applies them whilst logging the resulting changes to the current state of the document to patch_log

pub fn bundle<I>(&self, hashes: I) -> Result<Bundle, AutomergeError>

where I: IntoIterator<Item = ChangeHash>,

EXPERIMENTAL: Write the set of changes in hashes to a “bundle”

A “bundle” is a compact representation of a set of changes which uses the same compression tricks as the document encoding we use in Automerge::save.

This is an experimental API, the bundle format is still subject to change and so should not be used in production just yet.

pub fn save_with_options(&self, options: SaveOptions) -> Vec<u8>

Save the entirety of this document in a compact form.

pub fn save(&self) -> Vec<u8>

Save the entirety of this document in a compact form.

pub fn save_and_verify(&self) -> Result<Vec<u8>, AutomergeError>

Save the document and attempt to load it before returning - slow!

pub fn save_nocompress(&self) -> Vec<u8>

Save this document, but don’t run it through DEFLATE afterwards

pub fn save_after(&self, heads: &[ChangeHash]) -> Vec<u8>

Save the changes since the given heads

The output of this will not be a compressed document format, but a series of individual changes. This is useful if you know you have only made a small change since the last Self::save() and you want to immediately send it somewhere (e.g. you’ve inserted a single character in a text object).

pub fn get_last_local_change(&self) -> Option<Change>

Get the last change this actor made to the document.

pub fn dump(&self)

pub fn diff( &self, before_heads: &[ChangeHash], after_heads: &[ChangeHash], ) -> Vec<Patch>

Create patches representing the change in the current state of the document between the before and after heads. If the arguments are reverse it will observe the same changes in the opposite order.

pub fn diff_obj( &self, obj: &ExId, before_heads: &[ChangeHash], after_heads: &[ChangeHash], recursive: bool, ) -> Result<Vec<Patch>, AutomergeError>

Create patches representing the change in the current state of an object in the document between the before_heads and after_heads heads. If the arguments are reverse it will observe the same changes in the opposite order.

Arguments

• obj - The object to start the diff at.
• before_heads - heads from Self::get_heads() at beginning point in the documents history
• after_heads - heads from Self::get_heads() at ending point in the documents history.
• recursive - if false, do not also diff child objects

Note: before_heads and after_heads do not have to be chronological. Document state can move backward.

pub fn get_heads(&self) -> Vec<ChangeHash>

Get the heads of this document.

pub fn get_changes(&self, have_deps: &[ChangeHash]) -> Vec<Change>

pub fn get_changes_meta( &self, have_deps: &[ChangeHash], ) -> Vec<ChangeMetadata<'_>>

pub fn get_change_meta_by_hash( &self, hash: &ChangeHash, ) -> Option<ChangeMetadata<'_>>

pub fn get_changes_added(&self, other: &Self) -> Vec<Change>

Get changes in other that are not in self

pub fn hash_for_opid(&self, exid: &ExId) -> Option<ChangeHash>

Get the hash of the change that contains the given opid.

Returns None if the opid:

• is the root object id
• does not exist in this document

pub fn hydrate(&self, heads: Option<&[ChangeHash]>) -> Value

pub fn has_our_changes(&self, other: &State) -> bool

Whether the peer represented by other has all the changes we have

pub fn text_encoding(&self) -> TextEncoding

impl Automerge

pub fn apply_changes_batch( &mut self, changes: impl IntoIterator<Item = Change> + Clone, ) -> Result<(), AutomergeError>

pub fn apply_changes_batch_log_patches<I: IntoIterator<Item = Change>>( &mut self, changes: I, log: &mut PatchLog, ) -> Result<(), AutomergeError>

Trait Implementations

impl Clone for Automerge

fn clone(&self) -> Automerge

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Automerge

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

Formats the value using the given formatter.

impl Default for Automerge

fn default() -> Self

Returns the “default value” for a type.

impl ReadDoc for Automerge

fn parents<O: AsRef<ExId>>(&self, obj: O) -> Result<Parents<'_>, AutomergeError>

Get the parents of an object in the document tree.

fn parents_at<O: AsRef<ExId>>( &self, obj: O, heads: &[ChangeHash], ) -> Result<Parents<'_>, AutomergeError>

Get the parents of the object obj as at heads

fn keys<O: AsRef<ExId>>(&self, obj: O) -> Keys<'_>

Get the keys of the object obj.

fn keys_at<O: AsRef<ExId>>(&self, obj: O, heads: &[ChangeHash]) -> Keys<'_>

Get the keys of the object obj as at heads

fn iter_at<O: AsRef<ExId>>( &self, obj: O, heads: Option<&[ChangeHash]>, ) -> DocIter<'_>

Iterate over the object obj as at heads

fn map_range<'a, O: AsRef<ExId>, R: RangeBounds<String> + 'a>( &'a self, obj: O, range: R, ) -> MapRange<'a>

Iterate over the keys and values of the map obj in the given range.

fn map_range_at<'a, O: AsRef<ExId>, R: RangeBounds<String> + 'a>( &'a self, obj: O, range: R, heads: &[ChangeHash], ) -> MapRange<'a>

Iterate over the keys and values of the map obj in the given range as at heads

fn list_range<O: AsRef<ExId>, R: RangeBounds<usize>>( &self, obj: O, range: R, ) -> ListRange<'_>

Iterate over the indexes and values of the list or text obj in the given range.

fn list_range_at<O: AsRef<ExId>, R: RangeBounds<usize>>( &self, obj: O, range: R, heads: &[ChangeHash], ) -> ListRange<'_>

Iterate over the indexes and values of the list or text obj in the given range as at heads

fn values<O: AsRef<ExId>>(&self, obj: O) -> Values<'_>

Iterate over the values in a map, list, or text object

fn values_at<O: AsRef<ExId>>(&self, obj: O, heads: &[ChangeHash]) -> Values<'_>

Iterate over the values in a map, list, or text object as at heads

fn length<O: AsRef<ExId>>(&self, obj: O) -> usize

Get the length of the given object.

fn length_at<O: AsRef<ExId>>(&self, obj: O, heads: &[ChangeHash]) -> usize

Get the length of the given object as at heads

fn text<O: AsRef<ExId>>(&self, obj: O) -> Result<String, AutomergeError>

Get the string represented by the given text object.

fn spans<O: AsRef<ExId>>(&self, obj: O) -> Result<Spans<'_>, AutomergeError>

Return the sequence of text and block markers in the text object obj

fn spans_at<O: AsRef<ExId>>( &self, obj: O, heads: &[ChangeHash], ) -> Result<Spans<'_>, AutomergeError>

Return the sequence of text and block markers in the text object obj as at heads

fn get_cursor<O: AsRef<ExId>, I: Into<CursorPosition>>( &self, obj: O, position: I, at: Option<&[ChangeHash]>, ) -> Result<Cursor, AutomergeError>

Obtain the stable address (Cursor) for a usize position in a Sequence (either ObjType::List or ObjType::Text).

fn get_cursor_moving<O: AsRef<ExId>, I: Into<CursorPosition>>( &self, obj: O, position: I, at: Option<&[ChangeHash]>, move_cursor: MoveCursor, ) -> Result<Cursor, AutomergeError>

Obtain the stable address (Cursor) for a usize position in a Sequence (either ObjType::List or ObjType::Text).

fn get_cursor_position<O: AsRef<ExId>>( &self, obj: O, cursor: &Cursor, at: Option<&[ChangeHash]>, ) -> Result<usize, AutomergeError>

Translate Cursor in a Sequence into an absolute position of type usize.

fn text_at<O: AsRef<ExId>>( &self, obj: O, heads: &[ChangeHash], ) -> Result<String, AutomergeError>

Get the string represented by the given text object as at heads, see Self::text()

fn marks<O: AsRef<ExId>>(&self, obj: O) -> Result<Vec<Mark>, AutomergeError>

Get all marks on a current sequence

fn marks_at<O: AsRef<ExId>>( &self, obj: O, heads: &[ChangeHash], ) -> Result<Vec<Mark>, AutomergeError>

Get all marks on a sequence at a given heads

fn hydrate<O: AsRef<ExId>>( &self, obj: O, heads: Option<&[ChangeHash]>, ) -> Result<Value, AutomergeError>

fn get_marks<O: AsRef<ExId>>( &self, obj: O, index: usize, heads: Option<&[ChangeHash]>, ) -> Result<MarkSet, AutomergeError>

fn get<O: AsRef<ExId>, P: Into<Prop>>( &self, obj: O, prop: P, ) -> Result<Option<(Value<'_>, ExId)>, AutomergeError>

Get a value out of the document.

fn get_at<O: AsRef<ExId>, P: Into<Prop>>( &self, obj: O, prop: P, heads: &[ChangeHash], ) -> Result<Option<(Value<'_>, ExId)>, AutomergeError>

Get the value of the given key as at heads, see Self::get()

fn get_all<O: AsRef<ExId>, P: Into<Prop>>( &self, obj: O, prop: P, ) -> Result<Vec<(Value<'_>, ExId)>, AutomergeError>

Get all conflicting values out of the document at this prop that conflict.

fn get_all_at<O: AsRef<ExId>, P: Into<Prop>>( &self, obj: O, prop: P, heads: &[ChangeHash], ) -> Result<Vec<(Value<'_>, ExId)>, AutomergeError>

Get all possibly conflicting values for a key as at heads

fn object_type<O: AsRef<ExId>>(&self, obj: O) -> Result<ObjType, AutomergeError>

Get the type of this object, if it is an object.

fn get_missing_deps(&self, heads: &[ChangeHash]) -> Vec<ChangeHash>

Get the hashes of the changes in this document that aren’t transitive dependencies of the given heads.

fn get_change_by_hash(&self, hash: &ChangeHash) -> Option<Change>

Get a change by its hash.

fn stats(&self) -> Stats

Return some statistics about the document

fn text_encoding(&self) -> TextEncoding

fn iter(&self) -> DocIter<'_>

Iterate over all the objects in the document

impl SyncDoc for Automerge

fn generate_sync_message(&self, sync_state: &mut State) -> Option<Message>

Generate a sync message for the remote peer represented by sync_state

fn receive_sync_message( &mut self, sync_state: &mut State, message: Message, ) -> Result<(), AutomergeError>

Apply a received sync message to this document and sync_state

fn receive_sync_message_log_patches( &mut self, sync_state: &mut State, message: Message, patch_log: &mut PatchLog, ) -> Result<(), AutomergeError>

Apply a received sync message to this document and sync_state, logging any changes that are made to patch_log