pub struct Automerge { /* private fields */ }
Expand description
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§
source§impl Automerge
impl Automerge
sourcepub fn with_actor(self, actor: ActorId) -> Self
pub fn with_actor(self, actor: ActorId) -> Self
Set the actor id for this document.
sourcepub fn transaction(&mut self) -> Transaction<'_>
pub fn transaction(&mut self) -> Transaction<'_>
Start a transaction.
sourcepub fn transaction_log_patches(
&mut self,
patch_log: PatchLog
) -> Transaction<'_>
pub fn transaction_log_patches( &mut self, patch_log: PatchLog ) -> Transaction<'_>
Start a transaction which records changes in a PatchLog
sourcepub fn transaction_at(
&mut self,
patch_log: PatchLog,
heads: &[ChangeHash]
) -> Transaction<'_>
pub fn transaction_at( &mut self, patch_log: PatchLog, heads: &[ChangeHash] ) -> Transaction<'_>
Start a transaction isolated at a given heads
sourcepub fn transact<F, O, E>(&mut self, f: F) -> Result<O, E>
pub fn transact<F, O, E>(&mut self, f: F) -> Result<O, E>
Run a transaction on this document in a closure, automatically handling commit or rollback afterwards.
sourcepub fn transact_with<F, O, E, C>(&mut self, c: C, f: F) -> Result<O, E>
pub fn transact_with<F, O, E, C>(&mut self, c: C, f: F) -> Result<O, E>
Like Self::transact()
but with a function for generating the commit options.
sourcepub fn transact_and_log_patches<F, O, E>(
&mut self,
text_rep: TextRepresentation,
f: F
) -> Result<O, E>
pub fn transact_and_log_patches<F, O, E>( &mut self, text_rep: TextRepresentation, f: F ) -> 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()
sourcepub fn transact_and_log_patches_with<F, O, E, C>(
&mut self,
text_rep: TextRepresentation,
c: C,
f: F
) -> Result<O, E>
pub fn transact_and_log_patches_with<F, O, E, C>( &mut self, text_rep: TextRepresentation, c: C, f: F ) -> Result<O, E>
Like Self::transact_and_log_patches()
but with a function for generating the commit options
sourcepub fn empty_commit(&mut self, opts: CommitOptions) -> ChangeHash
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.
sourcepub fn fork(&self) -> Self
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
sourcepub fn fork_at(&self, heads: &[ChangeHash]) -> Result<Self, AutomergeError>
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
sourcepub fn load(data: &[u8]) -> Result<Self, AutomergeError>
pub fn load(data: &[u8]) -> Result<Self, AutomergeError>
Load a document.
sourcepub fn load_unverified_heads(data: &[u8]) -> Result<Self, AutomergeError>
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.
sourcepub 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
pub fn load_with( data: &[u8], on_error: OnPartialLoad, mode: VerificationMode, patch_log: &mut PatchLog ) -> Result<Self, AutomergeError>
load_with_options
insteadLoad a document, with options
§Arguments
data
- The data to loadon_error
- What to do if the document is only partially loaded. This can happen if some prefix ofdata
contains valid data.mode
- Whether to verify the head hashes after loadingpatch_log
- APatchLog
to log the changes required to materialize the current state of the document once loaded
sourcepub fn load_with_options<'a, 'b>(
data: &'a [u8],
options: LoadOptions<'b>
) -> Result<Self, AutomergeError>
pub fn load_with_options<'a, 'b>( data: &'a [u8], options: LoadOptions<'b> ) -> Result<Self, AutomergeError>
Load a document, with options
§Arguments
data
- The data to loadoptions
- The options to use when loading
sourcepub fn make_patches(&self, patch_log: &mut PatchLog) -> Vec<Patch>
pub fn make_patches(&self, patch_log: &mut PatchLog) -> Vec<Patch>
sourcepub fn current_state(&self, text_rep: TextRepresentation) -> Vec<Patch>
pub fn current_state(&self, text_rep: TextRepresentation) -> Vec<Patch>
Get a set of Patch
es which materialize the current state of the document
This is a convienence method for doc.diff(&[], current_heads)
sourcepub fn load_incremental(&mut self, data: &[u8]) -> Result<usize, AutomergeError>
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.
sourcepub fn load_incremental_log_patches(
&mut self,
data: &[u8],
patch_log: &mut PatchLog
) -> Result<usize, AutomergeError>
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
sourcepub fn apply_changes(
&mut self,
changes: impl IntoIterator<Item = Change>
) -> Result<(), AutomergeError>
pub fn apply_changes( &mut self, changes: impl IntoIterator<Item = Change> ) -> 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.
sourcepub fn apply_changes_log_patches<I: IntoIterator<Item = Change>>(
&mut self,
changes: I,
patch_log: &mut PatchLog
) -> Result<(), AutomergeError>
pub fn apply_changes_log_patches<I: IntoIterator<Item = Change>>( &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
sourcepub fn merge(
&mut self,
other: &mut Self
) -> Result<Vec<ChangeHash>, AutomergeError>
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
sourcepub fn merge_and_log_patches(
&mut self,
other: &mut Self,
patch_log: &mut PatchLog
) -> Result<Vec<ChangeHash>, AutomergeError>
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
sourcepub fn save_with_options(&self, options: SaveOptions) -> Vec<u8>
pub fn save_with_options(&self, options: SaveOptions) -> Vec<u8>
Save the entirety of this document in a compact form.
sourcepub fn save_and_verify(&self) -> Result<Vec<u8>, AutomergeError>
pub fn save_and_verify(&self) -> Result<Vec<u8>, AutomergeError>
Save the document and attempt to load it before returning - slow!
sourcepub fn save_nocompress(&self) -> Vec<u8>
pub fn save_nocompress(&self) -> Vec<u8>
Save this document, but don’t run it through DEFLATE
afterwards
sourcepub fn save_after(&self, heads: &[ChangeHash]) -> Vec<u8>
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).
sourcepub fn get_last_local_change(&self) -> Option<&Change>
pub fn get_last_local_change(&self) -> Option<&Change>
Get the last change this actor made to the document.
pub fn dump(&self)
sourcepub fn diff(
&self,
before_heads: &[ChangeHash],
after_heads: &[ChangeHash],
text_rep: TextRepresentation
) -> Vec<Patch>
pub fn diff( &self, before_heads: &[ChangeHash], after_heads: &[ChangeHash], text_rep: TextRepresentation ) -> 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.
sourcepub fn get_heads(&self) -> Vec<ChangeHash>
pub fn get_heads(&self) -> Vec<ChangeHash>
Get the heads of this document.
pub fn get_changes(&self, have_deps: &[ChangeHash]) -> Vec<&Change>
sourcepub fn get_changes_added<'a>(&self, other: &'a Self) -> Vec<&'a Change>
pub fn get_changes_added<'a>(&self, other: &'a Self) -> Vec<&'a Change>
Get changes in other
that are not in self
sourcepub fn hash_for_opid(&self, exid: &ExId) -> Option<ChangeHash>
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
Trait Implementations§
source§impl ReadDoc for Automerge
impl ReadDoc for Automerge
source§fn parents<O: AsRef<ExId>>(&self, obj: O) -> Result<Parents<'_>, AutomergeError>
fn parents<O: AsRef<ExId>>(&self, obj: O) -> Result<Parents<'_>, AutomergeError>
source§fn parents_at<O: AsRef<ExId>>(
&self,
obj: O,
heads: &[ChangeHash]
) -> Result<Parents<'_>, AutomergeError>
fn parents_at<O: AsRef<ExId>>( &self, obj: O, heads: &[ChangeHash] ) -> Result<Parents<'_>, AutomergeError>
source§fn keys<O: AsRef<ExId>>(&self, obj: O) -> Keys<'_> ⓘ
fn keys<O: AsRef<ExId>>(&self, obj: O) -> Keys<'_> ⓘ
obj
. Read moresource§fn map_range<'a, O: AsRef<ExId>, R: RangeBounds<String> + 'a>(
&'a self,
obj: O,
range: R
) -> MapRange<'a, R> ⓘ
fn map_range<'a, O: AsRef<ExId>, R: RangeBounds<String> + 'a>( &'a self, obj: O, range: R ) -> MapRange<'a, R> ⓘ
obj
in the given range. Read moresource§fn map_range_at<'a, O: AsRef<ExId>, R: RangeBounds<String> + 'a>(
&'a self,
obj: O,
range: R,
heads: &[ChangeHash]
) -> MapRange<'a, R> ⓘ
fn map_range_at<'a, O: AsRef<ExId>, R: RangeBounds<String> + 'a>( &'a self, obj: O, range: R, heads: &[ChangeHash] ) -> MapRange<'a, R> ⓘ
source§fn list_range<O: AsRef<ExId>, R: RangeBounds<usize>>(
&self,
obj: O,
range: R
) -> ListRange<'_, R> ⓘ
fn list_range<O: AsRef<ExId>, R: RangeBounds<usize>>( &self, obj: O, range: R ) -> ListRange<'_, R> ⓘ
obj
in the given range. Read moresource§fn list_range_at<O: AsRef<ExId>, R: RangeBounds<usize>>(
&self,
obj: O,
range: R,
heads: &[ChangeHash]
) -> ListRange<'_, R> ⓘ
fn list_range_at<O: AsRef<ExId>, R: RangeBounds<usize>>( &self, obj: O, range: R, heads: &[ChangeHash] ) -> ListRange<'_, R> ⓘ
obj
in the given range as at heads
Read moresource§fn values<O: AsRef<ExId>>(&self, obj: O) -> Values<'_> ⓘ
fn values<O: AsRef<ExId>>(&self, obj: O) -> Values<'_> ⓘ
source§fn values_at<O: AsRef<ExId>>(&self, obj: O, heads: &[ChangeHash]) -> Values<'_> ⓘ
fn values_at<O: AsRef<ExId>>(&self, obj: O, heads: &[ChangeHash]) -> Values<'_> ⓘ
heads
Read moresource§fn length<O: AsRef<ExId>>(&self, obj: O) -> usize
fn length<O: AsRef<ExId>>(&self, obj: O) -> usize
source§fn length_at<O: AsRef<ExId>>(&self, obj: O, heads: &[ChangeHash]) -> usize
fn length_at<O: AsRef<ExId>>(&self, obj: O, heads: &[ChangeHash]) -> usize
heads
Read moresource§fn text<O: AsRef<ExId>>(&self, obj: O) -> Result<String, AutomergeError>
fn text<O: AsRef<ExId>>(&self, obj: O) -> Result<String, AutomergeError>
source§fn spans<O: AsRef<ExId>>(&self, obj: O) -> Result<Spans<'_>, AutomergeError>
fn spans<O: AsRef<ExId>>(&self, obj: O) -> Result<Spans<'_>, AutomergeError>
obj
source§fn spans_at<O: AsRef<ExId>>(
&self,
obj: O,
heads: &[ChangeHash]
) -> Result<Spans<'_>, AutomergeError>
fn spans_at<O: AsRef<ExId>>( &self, obj: O, heads: &[ChangeHash] ) -> Result<Spans<'_>, AutomergeError>
obj
as at heads
source§fn get_cursor<O: AsRef<ExId>>(
&self,
obj: O,
position: usize,
at: Option<&[ChangeHash]>
) -> Result<Cursor, AutomergeError>
fn get_cursor<O: AsRef<ExId>>( &self, obj: O, position: usize, at: Option<&[ChangeHash]> ) -> Result<Cursor, AutomergeError>
usize
position in a Sequence (either ObjType::List
or ObjType::Text
). Read moresource§fn get_cursor_position<O: AsRef<ExId>>(
&self,
obj: O,
cursor: &Cursor,
at: Option<&[ChangeHash]>
) -> Result<usize, AutomergeError>
fn get_cursor_position<O: AsRef<ExId>>( &self, obj: O, cursor: &Cursor, at: Option<&[ChangeHash]> ) -> Result<usize, AutomergeError>
source§fn text_at<O: AsRef<ExId>>(
&self,
obj: O,
heads: &[ChangeHash]
) -> Result<String, AutomergeError>
fn text_at<O: AsRef<ExId>>( &self, obj: O, heads: &[ChangeHash] ) -> Result<String, AutomergeError>
heads
, see
Self::text()
source§fn marks<O: AsRef<ExId>>(&self, obj: O) -> Result<Vec<Mark<'_>>, AutomergeError>
fn marks<O: AsRef<ExId>>(&self, obj: O) -> Result<Vec<Mark<'_>>, AutomergeError>
source§fn marks_at<O: AsRef<ExId>>(
&self,
obj: O,
heads: &[ChangeHash]
) -> Result<Vec<Mark<'_>>, AutomergeError>
fn marks_at<O: AsRef<ExId>>( &self, obj: O, heads: &[ChangeHash] ) -> Result<Vec<Mark<'_>>, AutomergeError>
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>
source§fn get<O: AsRef<ExId>, P: Into<Prop>>(
&self,
obj: O,
prop: P
) -> Result<Option<(Value<'_>, ExId)>, AutomergeError>
fn get<O: AsRef<ExId>, P: Into<Prop>>( &self, obj: O, prop: P ) -> Result<Option<(Value<'_>, ExId)>, AutomergeError>
source§fn get_at<O: AsRef<ExId>, P: Into<Prop>>(
&self,
obj: O,
prop: P,
heads: &[ChangeHash]
) -> Result<Option<(Value<'_>, ExId)>, AutomergeError>
fn get_at<O: AsRef<ExId>, P: Into<Prop>>( &self, obj: O, prop: P, heads: &[ChangeHash] ) -> Result<Option<(Value<'_>, ExId)>, AutomergeError>
heads
, see Self::get()
source§fn get_all<O: AsRef<ExId>, P: Into<Prop>>(
&self,
obj: O,
prop: P
) -> Result<Vec<(Value<'_>, ExId)>, AutomergeError>
fn get_all<O: AsRef<ExId>, P: Into<Prop>>( &self, obj: O, prop: P ) -> Result<Vec<(Value<'_>, ExId)>, AutomergeError>
source§fn get_all_at<O: AsRef<ExId>, P: Into<Prop>>(
&self,
obj: O,
prop: P,
heads: &[ChangeHash]
) -> Result<Vec<(Value<'_>, ExId)>, AutomergeError>
fn get_all_at<O: AsRef<ExId>, P: Into<Prop>>( &self, obj: O, prop: P, heads: &[ChangeHash] ) -> Result<Vec<(Value<'_>, ExId)>, AutomergeError>
heads
Read moresource§fn object_type<O: AsRef<ExId>>(&self, obj: O) -> Result<ObjType, AutomergeError>
fn object_type<O: AsRef<ExId>>(&self, obj: O) -> Result<ObjType, AutomergeError>
source§fn get_missing_deps(&self, heads: &[ChangeHash]) -> Vec<ChangeHash>
fn get_missing_deps(&self, heads: &[ChangeHash]) -> Vec<ChangeHash>
heads
.source§fn get_change_by_hash(&self, hash: &ChangeHash) -> Option<&Change>
fn get_change_by_hash(&self, hash: &ChangeHash) -> Option<&Change>
source§impl SyncDoc for Automerge
impl SyncDoc for Automerge
source§fn generate_sync_message(&self, sync_state: &mut State) -> Option<Message>
fn generate_sync_message(&self, sync_state: &mut State) -> Option<Message>
sync_state
Read moresource§fn receive_sync_message(
&mut self,
sync_state: &mut State,
message: Message
) -> Result<(), AutomergeError>
fn receive_sync_message( &mut self, sync_state: &mut State, message: Message ) -> Result<(), AutomergeError>
sync_state
source§fn receive_sync_message_log_patches(
&mut self,
sync_state: &mut State,
message: Message,
patch_log: &mut PatchLog
) -> Result<(), AutomergeError>
fn receive_sync_message_log_patches( &mut self, sync_state: &mut State, message: Message, patch_log: &mut PatchLog ) -> Result<(), AutomergeError>
sync_state
, logging any changes that
are made to patch_log
Read more