Struct automerge::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_with.

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

Observers

Many of the methods on this type have an _with or _observed variant which allow you to pass in an OpObserver to observe any changes which occur.

Implementations

impl Automerge

pub fn new() -> Self

Create a new document with a random actor id.

pub fn is_empty(&self) -> bool

Whether this document has any operations

pub fn with_encoding(self, encoding: TextEncoding) -> Self

Change the text encoding of this view of the document

This is a cheap operation, it just changes the way indexes are calculated

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<'_, UnObserved>

Start a transaction.

pub fn transaction_with_observer<Obs: OpObserver + BranchableObserver>(
    &mut self,
    op_observer: Obs
) -> Transaction<'_, Observed<Obs>>

Start a transaction with an observer

pub fn transact<F, O, E>(&mut self, f: F) -> Result<O, (), E>where
    F: FnOnce(&mut Transaction<'_, UnObserved>) -> 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<'_, UnObserved>) -> Result<O, E>,
    C: FnOnce(&O) -> CommitOptions,

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

pub fn transact_observed<F, O, E, Obs>(&mut self, f: F) -> Result<O, Obs, E>where
    F: FnOnce(&mut Transaction<'_, Observed<Obs>>) -> Result<O, E>,
    Obs: OpObserver + BranchableObserver + Default,

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

pub fn transact_observed_with<F, O, E, C, Obs>(
    &mut self,
    c: C,
    f: F
) -> Result<O, Obs, E>where
    F: FnOnce(&mut Transaction<'_, Observed<Obs>>) -> Result<O, E>,
    C: FnOnce(&O) -> CommitOptions,
    Obs: OpObserver + BranchableObserver + Default,

Like Self::transact_observed 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 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<Obs: OpObserver>(
    data: &[u8],
    on_error: OnPartialLoad,
    mode: VerificationMode,
    observer: Option<&mut Obs>
) -> Result<Self, AutomergeError>

Load a document with an observer

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

Load an incremental save of a document.

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

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

pub fn load_incremental_with<Obs: OpObserver>(
    &mut self,
    data: &[u8],
    op_observer: Option<&mut Obs>
) -> Result<usize, AutomergeError>

Like Self::load_incremental but with an observer

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

Apply changes to this document.

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

pub fn apply_changes_with<I: IntoIterator<Item = Change>, Obs: OpObserver>(
    &mut self,
    changes: I,
    op_observer: Option<&mut Obs>
) -> Result<(), AutomergeError>

Like Self::apply_changes but with an observer

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_with<Obs: OpObserver>(
    &mut self,
    other: &mut Self,
    op_observer: Option<&mut Obs>
) -> Result<Vec<ChangeHash>, AutomergeError>

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

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

Save the entirety of this document in a compact form.

This takes a mutable reference to self because it saves the heads of the last save so that save_incremental can be used to produce only the changes since the last save. This API will be changing in future.

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

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

pub fn save_incremental(&mut self) -> Vec<u8>

Save the changes since the last call to Self::save`

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 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 visualise_optree(&self, objects: Option<Vec<ExId>>) -> String

Return a graphviz representation of the opset.

Arguments

• objects: An optional list of object IDs to display, if not specified all objects are visualised

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

Get the heads of this document.

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

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

Get changes in other that are not in `self

Trait Implementations

impl Clone for Automerge

fn clone(&self) -> Automerge

Returns a copy 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 path_to_object<O: AsRef<ExId>>(
    &self,
    obj: O
) -> Result<Vec<(ExId, Prop)>, AutomergeError>

Get the path to an object

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]) -> KeysAt<'_, '_>

Get the keys of the object obj as at heads

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

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

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

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<'_, R>

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]
) -> ListRangeAt<'_, R>

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 object_type<O: AsRef<ExId>>(&self, obj: O) -> Result<ObjType, AutomergeError>

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

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

Get the string represented by the given text object.

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 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 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.

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_with<Obs: OpObserver>(
    &mut self,
    sync_state: &mut State,
    message: Message,
    op_observer: &mut Obs
) -> Result<(), AutomergeError>

Apply a received sync message to this document and sync_state, observing any changes with op_observer