Struct automerge::AutoCommitWithObs

pub struct AutoCommitWithObs<Obs: Observation> { /* private fields */ }

An automerge document that automatically manages transactions.

An AutoCommit can optionally manage an OpObserver. This observer will be notified of all changes made by both remote and local changes. The type parameter O tracks whether this document is observed or not.

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.

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

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

This type implements Transactable directly, so you can modify it using methods from Transactable.

Synchronization

To synchronise call Self::sync which returns an implementation of SyncDoc

Observers

An AutoCommit can optionally manage an OpObserver. Self::new will return a document with no observer but you can set an observer using Self::with_observer. The observer must implement both OpObserver and BranchableObserver. If you have an observed autocommit then you can obtain a mutable reference to the observer with Self::observer

Implementations

impl AutoCommitWithObs<UnObserved>

pub fn new() -> AutoCommit

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

impl<Obs: OpObserver + BranchableObserver> AutoCommitWithObs<Observed<Obs>>

pub fn observer(&mut self) -> &mut Obs

impl<Obs: Observation + Clone> AutoCommitWithObs<Obs>

pub fn fork(&mut self) -> Self

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

impl<Obs: Observation> AutoCommitWithObs<Obs>

pub fn with_observer<Obs2: OpObserver + BranchableObserver>(
    self,
    op_observer: Obs2
) -> AutoCommitWithObs<Observed<Obs2>>

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

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

pub fn get_actor(&self) -> &ActorId

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 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 apply_changes(
    &mut self,
    changes: impl IntoIterator<Item = Change>
) -> Result<(), AutomergeError>

pub fn merge<Obs2: Observation>(
    &mut self,
    other: &mut AutoCommitWithObs<Obs2>
) -> 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.

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_missing_deps(&mut self, heads: &[ChangeHash]) -> Vec<ChangeHash>

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

Get the last change made by this documents actor ID

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

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

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

Get changes in other that are not in `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(&mut self) -> Vec<ChangeHash>

Get the current heads of the document.

This closes the transaction first, if one is in progress.

pub fn commit(&mut self) -> Option<ChangeHash>

Commit any uncommitted changes

Returns None if there were no operations to commit

pub fn commit_with(&mut self, options: CommitOptions) -> Option<ChangeHash>

Commit the current operations with some options.

Returns None if there were no operations to commit

let mut doc = AutoCommit::new();
doc.put_object(&ROOT, "todos", ObjType::List).unwrap();
let now = SystemTime::now().duration_since(SystemTime::UNIX_EPOCH).unwrap().as_secs() as
i64;
doc.commit_with(CommitOptions::default().with_message("Create todos list").with_time(now));

pub fn rollback(&mut self) -> usize

Remove any changes that have been made in the current transaction from the document

pub fn empty_change(&mut self, options: CommitOptions) -> ChangeHash

Generate an empty change

The main reason to do this is if you wish to create a “merge commit” which has all the current heads of the documents as dependencies but you have no new operations to create.

Because this structure is an “autocommit” there may actually be outstanding operations to submit. If this is the case this function will create two changes, one with the outstanding operations and a new one with no operations. The returned ChangeHash will always be the hash of the empty change.

pub fn sync(&mut self) -> impl SyncDoc + '_

An implementation of crate::sync::SyncDoc for this autocommit

This ensures that any outstanding transactions for this document are committed before taking part in the sync protocol

Trait Implementations

impl<Obs: Clone + Observation> Clone for AutoCommitWithObs<Obs>

fn clone(&self) -> AutoCommitWithObs<Obs>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Obs: Debug + Observation> Debug for AutoCommitWithObs<Obs>

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

Formats the value using the given formatter.

impl<O: OpObserver + BranchableObserver + Default> Default for AutoCommitWithObs<Observed<O>>

fn default() -> Self

Returns the “default value” for a type.

impl<Obs: Observation> ReadDoc for AutoCommitWithObs<Obs>

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<Obs: Observation> Transactable for AutoCommitWithObs<Obs>

fn splice<O: AsRef<ExId>, V: IntoIterator<Item = ScalarValue>>(
    &mut self,
    obj: O,
    pos: usize,
    del: usize,
    vals: V
) -> Result<(), AutomergeError>

Splice new elements into the given sequence. Returns a vector of the OpIds used to insert the new elements

fn pending_ops(&self) -> usize

Get the number of pending operations in this transaction.

fn put<O: AsRef<ExId>, P: Into<Prop>, V: Into<ScalarValue>>(
    &mut self,
    obj: O,
    prop: P,
    value: V
) -> Result<(), AutomergeError>

Set the value of property P to value V in object obj.

fn put_object<O: AsRef<ExId>, P: Into<Prop>>(
    &mut self,
    obj: O,
    prop: P,
    value: ObjType
) -> Result<ExId, AutomergeError>

Set the value of property P to the new object V in object obj.

fn insert<O: AsRef<ExId>, V: Into<ScalarValue>>(
    &mut self,
    obj: O,
    index: usize,
    value: V
) -> Result<(), AutomergeError>

Insert a value into a list at the given index.

fn insert_object<O: AsRef<ExId>>(
    &mut self,
    obj: O,
    index: usize,
    value: ObjType
) -> Result<ExId, AutomergeError>

Insert an object into a list at the given index.

fn increment<O: AsRef<ExId>, P: Into<Prop>>(
    &mut self,
    obj: O,
    prop: P,
    value: i64
) -> Result<(), AutomergeError>

Increment the counter at the prop in the object by value.

fn delete<O: AsRef<ExId>, P: Into<Prop>>(
    &mut self,
    obj: O,
    prop: P
) -> Result<(), AutomergeError>

Delete the value at prop in the object.

fn splice_text<O: AsRef<ExId>>(
    &mut self,
    obj: O,
    pos: usize,
    del: usize,
    text: &str
) -> Result<(), AutomergeError>

Like Self::splice but for text.

fn base_heads(&self) -> Vec<ChangeHash>

The heads this transaction will be based on