tagtree 0.1.2

Hierarchical tag paths and an in-memory tag index for Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

use std::{hash::Hash, iter};

use crate::treebag::{Tree, TreeResult, TreeView};

/// An item's persisted tag assignment after a path mutation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TagAssignment<T> {
    pub item: T,
    pub tags: Vec<String>,
}

/// A read-only summary of a tag index.
pub struct TagIndexSummary {
    pub tree: TreeView,
    /// Number of paths with directly assigned items, including the untagged root.
    pub assigned_path_count: usize,
    pub untagged_count: usize,
}

/// A hierarchical, multi-tag index that owns untagged-item semantics.
#[derive(Debug)]
pub struct TagIndex<T> {
    tree: Tree<T>,
}

impl<T: Eq + Hash + Clone> TagIndex<T> {
    pub fn new() -> Self {
        Self {
            tree: Tree::new(""),
        }
    }

    /// Inserts an item or replaces all of its existing tags.
    pub fn upsert(&mut self, item: &T, tags: &[String]) {
        let old_paths = self.tree.get_item_paths(item);
        let new_paths = paths_for_storage(tags);

        if old_paths == new_paths {
            return;
        }

        self.tree.move_item(item, &old_paths, &new_paths);
    }

    /// Removes an item without requiring callers to provide its old tags.
    pub fn remove(&mut self, item: &T) {
        let old_paths = self.tree.get_item_paths(item);
        self.tree.delete_item(item, &old_paths);
    }

    /// Returns persisted tags without exposing the internal untagged root path.
    pub fn tags(&self, item: &T) -> Vec<String> {
        self.tree
            .get_item_paths(item)
            .into_iter()
            .filter(|path| !path.is_empty())
            .collect()
    }

    pub fn summary(&self) -> TagIndexSummary {
        TagIndexSummary {
            tree: self.tree.view(),
            assigned_path_count: self.tree.list_paths().len(),
            untagged_count: self.tree.root_bag_count(),
        }
    }
}

impl<T: Eq + Hash + Clone + Ord> TagIndex<T> {
    /// Returns items assigned to a path or any descendant in descending order.
    pub fn items(&self, path: &str) -> TreeResult<Vec<T>> {
        let mut items = self
            .tree
            .get_items(path)?
            .into_iter()
            .cloned()
            .collect::<Vec<_>>();
        items.sort_unstable_by(|left, right| right.cmp(left));
        Ok(items)
    }

    /// Renames or merges a path and returns assignments for affected items.
    pub fn rename_path(
        &mut self,
        old_path: &str,
        new_path: &str,
    ) -> TreeResult<Vec<TagAssignment<T>>> {
        let affected_items = self.items(old_path)?;
        self.tree.move_path(old_path, new_path)?;
        Ok(self.assignments(affected_items))
    }

    /// Removes a path subtree while preserving unrelated tags.
    pub fn delete_path(&mut self, path: &str) -> TreeResult<Vec<TagAssignment<T>>> {
        let affected_items = self.items(path)?;
        let descendant_prefix = format!("{path}/");

        for item in &affected_items {
            let old_paths = self.tree.get_item_paths(item);
            let retained_paths = old_paths
                .iter()
                .filter(|item_path| {
                    item_path.as_str() != path && !item_path.starts_with(&descendant_prefix)
                })
                .cloned()
                .collect::<Vec<_>>();
            let next_paths = if retained_paths.is_empty() {
                vec![String::new()]
            } else {
                retained_paths
            };

            self.tree.move_item(item, &old_paths, &next_paths);
        }

        Ok(self.assignments(affected_items))
    }

    fn assignments(&self, items: Vec<T>) -> Vec<TagAssignment<T>> {
        items
            .into_iter()
            .map(|item| TagAssignment {
                tags: self.tags(&item),
                item,
            })
            .collect()
    }
}

impl<T: Eq + Hash + Clone> Default for TagIndex<T> {
    fn default() -> Self {
        Self::new()
    }
}

fn paths_for_storage(tags: &[String]) -> Vec<String> {
    if tags.is_empty() {
        return iter::once(String::new()).collect();
    }

    let mut paths = tags.to_vec();
    paths.sort();
    paths.dedup();
    paths
}