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

Authors and Actors

It’s often useful to be able to know who made some change. For this purpose Automerge has the concept of an “author ID”. An author ID is an opaque byte array which can be associated with a change. This author ID will become part of the document history so you can later examine the changes in a document and see which author made the change.

Author IDs are set on document construction. If you don’t set an author then changes produced by the document will have no author (Change::author will return None).

Example

let author = Author::from(vec![1,2,3]);
let mut doc = Automerge::new().with_author(Some(author.clone()));
doc.transact(|tx| {
    tx.put(ROOT, "foo", "bar")?;
    Ok::<_, AutomergeError>(())
}).unwrap();
let change = doc.get_last_local_change().unwrap();
assert_eq!(change.author().unwrap(), author);

Relationship to Actor IDs

Every automerge commit has an “actor ID”, which represents a sequential execution. Actor IDs should be considered a low level implementation detail and as much as possible should be left to automerge to manage.

Prior to the introduction of author IDs, actor IDs were often used in applications to determine authorship. New code should migrate to using author IDs. If you do need to map from an actor ID to an author ID you can use Automerge::get_author_for_actor.

Implementations

impl Automerge

pub fn new() -> Automerge

Create a new document with a random actor id.

pub fn anonymize(&self) -> Result<Automerge, AnonymizeError>

Return a copy of this document with its data anonymized using a fresh random seed.

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) -> Automerge

pub fn is_empty(&self) -> bool

Whether this document has any operations

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

Set the actor id for this document.

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

Set the actor id for this document.

pub fn with_author(self, author: Option<Author<'static>>) -> Automerge

Set the actor id for this document.

pub fn set_author(&mut self, author: Option<Author<'static>>) -> &mut Automerge

Set the author for this document.

The Author is only changed, if author differs from Automerge::get_author. If the author does change then a new ActorId is generated for that author. Notably, this could be a different ActorId compared to previous edits for the same author.

If you are using authors never manually manage the ActorId.

pub fn get_author(&self) -> Option<&Author<'static>>

Get the current author of this document.

pub fn get_actors_for_author(&self, author: &Author<'_>) -> Vec<ActorId>

pub fn get_authors(&self) -> &[Author<'static>]

pub fn get_author_for_actor(&self, actor: &ActorId) -> Option<Author<'_>>

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, ) -> Result<Transaction<'_>, PatchLogMismatch>

Start a transaction which records changes in a PatchLog

Returns PatchLogMismatch if patch_log does not belong to this document. This probably means a patch log created for one document was reused with another document.

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

Start a transaction isolated at a given heads

Returns PatchLogMismatch if patch_log does not belong to this document. This probably means a patch log created for one document was reused with another document.

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

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

Returns PatchLogMismatch if patch_log does not belong to this document. This probably means a patch log created for one document was reused with another document.

pub fn transact<F, O, E>(&mut self, f: F) -> Result<Success<O>, Failure<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<Success<O>, Failure<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<Success<O>, Failure<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<Success<O>, Failure<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) -> Automerge

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<Automerge, 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: &Automerge) -> Result<(), AutomergeError>

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

Load a document.

pub fn load_unverified_heads(data: &[u8]) -> Result<Automerge, 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<Automerge, 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<Automerge, AutomergeError>

Load a document, with options

Arguments

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

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

Best-effort rescue for documents which fail strict loading.

This returns only the current hydrated value and does not preserve the original change graph.

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 parse_changes(data: &[u8]) -> Result<Vec<Change>, AutomergeError>

The changes in data (what [Self::save_incremental] writes: one or more concatenated change chunks), parsed and checksummed but applied to no document, so a receiver can read each change’s hash, message and dependencies before deciding whether to merge it.

Errors

Returns the first chunk that does not parse.

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>( &mut self, changes: I, patch_log: &mut PatchLog, ) -> Result<(), AutomergeError>

where I: IntoIterator<Item = Change> + Clone,

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 Automerge, ) -> 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 Automerge, 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 change_hashes(&self) -> &[ChangeHash]

Every change’s hash, in the order Self::get_changes lists them for &[]: the order the changes were added to this document. Adding changes only appends to it, so a reader that read a prefix of the log can tell, without rebuilding any change, whether it still is one.

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: &Automerge) -> 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>( &mut self, changes: I, log: &mut PatchLog, ) -> Result<(), AutomergeError>

where I: IntoIterator<Item = Change>,

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<(), Error>

Formats the value using the given formatter.

impl Default for Automerge

fn default() -> Automerge

Returns the “default value” for a type.

impl ReadDoc for Automerge

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

where O: AsRef<ExId>,

Get the parents of an object in the document tree.

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

where O: AsRef<ExId>,

Get the parents of the object obj as at heads

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

where O: AsRef<ExId>,

Get the keys of the object obj.

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

where O: AsRef<ExId>,

Get the keys of the object obj as at heads

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

where O: AsRef<ExId>,

Iterate over the object obj as at heads

fn map_range<'a, O, R>(&'a self, obj: O, range: R) -> MapRange<'a>

where O: AsRef<ExId>, R: RangeBounds<String> + 'a,

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

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

where O: AsRef<ExId>, R: RangeBounds<String> + 'a,

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

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

where O: AsRef<ExId>, R: RangeBounds<usize>,

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

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

where O: AsRef<ExId>, R: RangeBounds<usize>,

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

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

where O: AsRef<ExId>,

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

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

where O: AsRef<ExId>,

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

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

where O: AsRef<ExId>,

Get the length of the given object.

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

where O: AsRef<ExId>,

Get the length of the given object as at heads

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

where O: AsRef<ExId>,

Get the string represented by the given text object.

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

where O: AsRef<ExId>,

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

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

where O: AsRef<ExId>,

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

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

where O: AsRef<ExId>, I: Into<CursorPosition>,

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

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

where O: AsRef<ExId>, I: Into<CursorPosition>,

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

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

where O: AsRef<ExId>,

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

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

where O: AsRef<ExId>,

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

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

where O: AsRef<ExId>,

Get all marks on a current sequence

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

where O: AsRef<ExId>,

Get all marks on a sequence at a given heads

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

where O: AsRef<ExId>,

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

where O: AsRef<ExId>,

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

where O: AsRef<ExId>, P: Into<Prop>,

Get a value out of the document.

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

where O: AsRef<ExId>, P: Into<Prop>,

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

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

where O: AsRef<ExId>, P: Into<Prop>,

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

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

where O: AsRef<ExId>, P: Into<Prop>,

Get all possibly conflicting values for a key as at heads

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

where O: AsRef<ExId>,

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