Struct Editor

pub struct Editor<'a> { /* private fields */ }

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

impl<'a> Editor<'a>

Cursor handling

pub fn to_cursor(&mut self) -> Cursor<'_, 'a>

Turn ourselves as a cursor, which points to the same tree as the editor.

This is useful if a method takes a Cursor, not an Editor.

pub fn cursor_at<I, C>(&mut self, rela_path: I) -> Result<Cursor<'_, 'a>, Error>

where I: IntoIterator<Item = C>, C: AsRef<BStr>,

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.

impl<'a> Editor<'a>

Lifecycle

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.

impl Editor<'_>

Operations

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.

pub fn remove<I, C>(&mut self, rela_path: I) -> Result<&mut Self, Error>

where I: IntoIterator<Item = C>, C: AsRef<BStr>,

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.

pub fn get<I, C>(&self, rela_path: I) -> Option<&Entry>

where I: IntoIterator<Item = C>, C: AsRef<BStr>,

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.

pub fn upsert<I, C>( &mut self, rela_path: I, kind: EntryKind, id: ObjectId, ) -> Result<&mut Self, Error>

where I: IntoIterator<Item = C>, C: AsRef<BStr>,

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.

pub fn set_root(&mut self, root: Tree) -> &mut Self

Set the root tree of the modification to root, assuring it has a well-known state.

Note that this erases all previous edits.

This is useful if the same editor is re-used for various trees.

Trait Implementations

impl<'a> Clone for Editor<'a>

fn clone(&self) -> Editor<'a>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Editor<'_>

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

Formats the value using the given formatter.