Struct Editor

pub struct Editor<'repo> {
    pub repo: &'repo Repository,
    /* private fields */
}

Available on crate feature tree-editor only.

All state needed to conveniently edit a tree, using only update-or-insert and removals.

Fields

repo: &'repo Repository

The owning repository.

Implementations

impl<'repo> Editor<'repo>

Lifecycle

pub fn new(tree: &Tree<'repo>) -> Result<Self, Error>

Initialize a new editor from the given tree.

pub fn detach(self) -> Editor<'repo>

Detach all extras and return the underlying plumbing editor, which won’t perform validation when writing the tree.

impl<'repo> Editor<'repo>

Cursor Handling

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

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( &mut self, rela_path: impl ToComponents, ) -> Result<Cursor<'_, 'repo>, 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.

impl<'repo> Editor<'repo>

Operations

pub fn set_root(&mut self, root: &Tree<'repo>) -> Result<&mut Self, Error>

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.

pub fn upsert( &mut self, rela_path: impl ToComponents, kind: EntryKind, id: impl Into<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.

Validation of path-components will not be performed here, but when writing the tree.

pub fn remove( &mut self, rela_path: impl ToComponents, ) -> 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.

pub fn write(&mut self) -> Result<Id<'repo>, Error>

Write the entire in-memory state of all changed trees (and only changed trees) to the object database. 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().

Before writing a tree, all of its entries (not only added ones), will be validated to assure they are correct. The objects pointed to by entries also have to exist already.

pub fn get(&self, rela_path: impl ToComponents) -> Option<EntryRef<'repo, '_>>

Obtain the entry at rela_path or return None if none was found, or the tree wasn’t yet written to that point. The root tree is always available. 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.

Trait Implementations

impl<'repo> Clone for Editor<'repo>

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

Returns a copy of the value.

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

Performs copy-assignment from source.