pub struct Editor<'a> { /* private fields */ }
Expand description
The state needed to apply edits instantly to in-memory trees.
It’s made so that each tree is looked at in the object database at most once, and held in memory for all edits until everything is flushed to write all changed trees.
The editor is optimized to edit existing trees, but can deal with building entirely new trees as well with some penalties.
Implementations§
Source§impl<'a> Editor<'a>
impl<'a> Editor<'a>
Cursor handling
Sourcepub fn cursor_at<I, C>(&mut self, rela_path: I) -> Result<Cursor<'_, 'a>, Error>
pub fn cursor_at<I, C>(&mut self, rela_path: I) -> Result<Cursor<'_, 'a>, Error>
Create a cursor at the given rela_path
, which must be a tree or is turned into a tree as its own edit.
The returned cursor will then allow applying edits to the tree at rela_path
as root.
If rela_path
is a single empty string, it is equivalent to using the current instance itself.
Source§impl<'a> Editor<'a>
impl<'a> Editor<'a>
Lifecycle
Sourcepub fn new(root: Tree, find: &'a dyn FindExt, object_hash: Kind) -> Self
pub fn new(root: Tree, find: &'a dyn FindExt, object_hash: Kind) -> Self
Create a new editor that uses root
as base for all edits. Use find
to lookup existing
trees when edits are made. Each tree will only be looked-up once and then edited in place from
that point on.
object_hash
denotes the kind of hash to create.
Source§impl Editor<'_>
impl Editor<'_>
Operations
Sourcepub fn write<E>(
&mut self,
out: impl FnMut(&Tree) -> Result<ObjectId, E>,
) -> Result<ObjectId, E>
pub fn write<E>( &mut self, out: impl FnMut(&Tree) -> Result<ObjectId, E>, ) -> Result<ObjectId, E>
Write the entire in-memory state of all changed trees (and only changed trees) to out
, and remove
written portions from our state except for the root tree, which affects get()
.
Note that the returned object id can be the empty tree if everything was removed or if nothing
was added to the tree.
The last call to out
will be the changed root tree, whose object-id will also be returned.
out
is free to do any kind of additional validation, like to assure that all entries in the tree exist.
We don’t assure that as there is no validation that inserted entries are valid object ids.
Future calls to upsert
or similar will keep working on the last seen state of the
just-written root-tree.
If this is not desired, use set_root().
§Validation
Note that no additional validation is performed to assure correctness of entry-names. It is absolutely and intentionally possible to write out invalid trees with this method. Higher layers are expected to perform detailed validation.
Sourcepub fn remove<I, C>(&mut self, rela_path: I) -> Result<&mut Self, Error>
pub fn remove<I, C>(&mut self, rela_path: I) -> Result<&mut Self, Error>
Remove the entry at rela_path
, loading all trees on the path accordingly.
It’s no error if the entry doesn’t exist, or if rela_path
doesn’t lead to an existing entry at all.
Note that trying to remove a path with an empty component is also forbidden.
Sourcepub fn get<I, C>(&self, rela_path: I) -> Option<&Entry>
pub fn get<I, C>(&self, rela_path: I) -> Option<&Entry>
Obtain the entry at rela_path
or return None
if none was found, or the tree wasn’t yet written
to that point.
Note that after writing only the root path remains, all other intermediate trees are removed.
The entry can be anything that can be stored in a tree, but may have a null-id if it’s a newly
inserted tree. Also, ids of trees might not be accurate as they may have been changed in memory.
Sourcepub fn upsert<I, C>(
&mut self,
rela_path: I,
kind: EntryKind,
id: ObjectId,
) -> Result<&mut Self, Error>
pub fn upsert<I, C>( &mut self, rela_path: I, kind: EntryKind, id: ObjectId, ) -> Result<&mut Self, Error>
Insert a new entry of kind
with id
at rela_path
, an iterator over each path component in the tree,
like a/b/c
. Names are matched case-sensitively.
Existing leaf-entries will be overwritten unconditionally, and it is assumed that id
is available in the object database
or will be made available at a later point to assure the integrity of the produced tree.
Intermediate trees will be created if they don’t exist in the object database, otherwise they will be loaded and entries will be inserted into them instead.
Note that id
can be null to create a placeholder. These will not be written, and paths leading
through them will not be considered a problem.
id
can also be an empty tree, along with the respective kind
, even though that’s normally not allowed
in Git trees.