Struct AutoCommit

pub struct AutoCommit { /* private fields */ }

An automerge document that automatically manages transactions.

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

Patches, maintaining materialized views

AutoCommit allows you to generate Patches representing changes to the current state of the document which you can use to maintain a materialized view of the current state. There are several ways to use this. See the documentation on Self::diff() for more details, but the key point to remember is that AutoCommit manages an internal “diff cursor” for you. This is a representation of the heads of the document last time you called Self::diff_incremental() but you can also manage it directly using Self::update_diff_cursor() and Self::reset_diff_cursor().

Implementations

impl AutoCommit

pub fn new() -> AutoCommit

pub fn new_with_encoding(encoding: TextEncoding) -> AutoCommit

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

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

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

👎Deprecated since 0.5.2: use load_with_options instead

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

pub fn reset_diff_cursor(&mut self)

Erases the diff cursor created by Self::update_diff_cursor() and no longer indexes changes to the document.

pub fn update_diff_cursor(&mut self)

Sets the Self::diff_cursor() to current heads of the document and will begin building an index with every change moving forward.

If Self::diff() is called with Self::diff_cursor() as before and Self::get_heads() as after - the index will be used

If the cursor is no longer needed it can be reset with Self::reset_diff_cursor()

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

Returns the cursor set by Self::update_diff_cursor()

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

Generate the patches recorded in patch_log

pub fn diff( &mut self, before: &[ChangeHash], after: &[ChangeHash], ) -> Vec<Patch>

Generates a diff from before to after

By default the diff requires a sequental scan of all the ops in the doc.

To do a fast indexed diff before must equal Self::diff_cursor() and after must equal Self::get_heads(). The diff cursor is managed with Self::update_diff_cursor() and Self::reset_diff_cursor()

Managing the diff index has a small but non-zero overhead. It should be disabled if no longer needed. If a signifigantly large change is applied to the document it may be faster to reset the index before applying it, doing an unindxed diff afterwards and then reenable the index.

Arguments

• before - heads from Self::get_heads() at beginning point in the documents history
• after - heads from Self::get_heads() at ending point in the documents history.

Note: before and after do not have to be chronological. Document state can move backward. Normal use might look like:

Example

use automerge::{ AutoCommit };

let mut doc = AutoCommit::new(); // or AutoCommit::load(data)
// make some changes - use and update the index
let heads = doc.get_heads();
let diff_cursor = doc.diff_cursor();
let patches = doc.diff(&diff_cursor, &heads);
doc.update_diff_cursor();

See Self::diff_incremental() for encapsulating this pattern.

pub fn diff_incremental(&mut self) -> Vec<Patch>

This is a convience function that encapsulates the following common pattern

use automerge::AutoCommit;
let mut doc = AutoCommit::new();
// make some changes
let heads = doc.get_heads();
let diff_cursor = doc.diff_cursor();
let patches = doc.diff(&diff_cursor, &heads);
doc.update_diff_cursor();

pub fn fork(&mut self) -> Self

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

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

pub fn integrate(&mut self)

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_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( &mut self, other: &mut AutoCommit, ) -> 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_with_options(&mut self, options: SaveOptions) -> Vec<u8>

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

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

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 Self::save() and you want to immediately send it somewhere (e.g. you’ve inserted a single character in a text object).

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

Save everything which is not a (transitive) dependency of heads

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]) -> Vec<&Change>

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 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 set_text_rep(&mut self, text_rep: TextRepresentation)

pub fn get_text_rep(&mut self) -> TextRepresentation

pub fn with_text_rep(self, text_rep: TextRepresentation) -> Self

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

pub fn hash_for_opid(&self, opid: &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
• Is for an operation in a transaction

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

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

Trait Implementations

impl Clone for AutoCommit

fn clone(&self) -> AutoCommit

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for AutoCommit

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

Formats the value using the given formatter.

impl Default for AutoCommit

An autocommit document with an inactive PatchLog

See AutoCommit

fn default() -> Self

Returns the “default value” for a type.

impl ReadDoc for AutoCommit

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 map_range<'a, O: AsRef<ExId>, R: RangeBounds<String> + 'a>( &'a self, obj: O, range: R, ) -> MapRange<'a, R>

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, 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], ) -> ListRange<'_, 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 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 get_marks<O: AsRef<ExId>>( &self, obj: O, index: usize, heads: Option<&[ChangeHash]>, ) -> Result<MarkSet, AutomergeError>

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 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 hydrate<O: AsRef<ExId>>( &self, obj: O, heads: Option<&[ChangeHash]>, ) -> Result<Value, 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 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

impl Transactable for AutoCommit

fn splice<O: AsRef<ExId>, V: IntoIterator<Item = ScalarValue>>( &mut self, obj: O, pos: usize, del: isize, 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: isize, text: &str, ) -> Result<(), AutomergeError>

Like Self::splice but for text.

fn mark<O: AsRef<ExId>>( &mut self, obj: O, mark: Mark<'_>, expand: ExpandMark, ) -> Result<(), AutomergeError>

Mark a sequence

fn unmark<O: AsRef<ExId>>( &mut self, obj: O, key: &str, start: usize, end: usize, expand: ExpandMark, ) -> Result<(), AutomergeError>

Remove a Mark from a sequence

fn split_block<'p, O>( &mut self, obj: O, index: usize, ) -> Result<ExId, AutomergeError>

where O: AsRef<ExId>,

Insert a block marker into the text object obj at the given index.

fn join_block<O: AsRef<ExId>>( &mut self, text: O, index: usize, ) -> Result<(), AutomergeError>

Delete a block marker at index from the text object obj.

fn replace_block<'p, O>( &mut self, text: O, index: usize, ) -> Result<ExId, AutomergeError>

where O: AsRef<ExId>,

Replace a block marker at index in obj with a new marker and return the ID of the new marker

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

The heads this transaction will be based on

fn update_text<S: AsRef<str>>( &mut self, obj: &ExId, new_text: S, ) -> Result<(), AutomergeError>

Update the value of a string

fn update_spans<'a, O: AsRef<ExId>, I: IntoIterator<Item = BlockOrText<'a>>>( &mut self, text: O, new_text: I, ) -> Result<(), AutomergeError>

Update the blocks and text in a text object

fn update_object<O: AsRef<ExId>>( &mut self, obj: O, new_value: &Value, ) -> Result<(), UpdateObjectError>