Skip to main content

vvv_engine/protocol/
reach.rs

1//! Who may name a declaration, computed from its modifier and its module.
2
3use serde::{Deserialize, Serialize};
4use vvv_core::{Address, PackageId, ReachKind};
5
6/// The set of modules that may name a declaration: a kind applied to the
7/// declaring module's address. Never declared, always computed.
8#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
9#[serde(rename_all = "snake_case")]
10pub enum Reach {
11    Within(Address),
12    Package(PackageId),
13    Everyone,
14}
15
16impl Reach {
17    /// `kind` applied to `declaring`. A `Path` kind needs its module
18    /// resolved by the caller; unresolved, it is treated as the declaring
19    /// module, the narrowest reading.
20    pub fn of(kind: ReachKind, declaring: &Address, path: Option<Address>) -> Self {
21        match kind {
22            ReachKind::Declaring => Self::Within(declaring.clone()),
23            ReachKind::Parent => {
24                Self::Within(declaring.parent().unwrap_or_else(|| declaring.clone()))
25            }
26            ReachKind::Package => Self::Package(declaring.package().clone()),
27            ReachKind::Everyone => Self::Everyone,
28            ReachKind::Path => Self::Within(path.unwrap_or_else(|| declaring.clone())),
29        }
30    }
31
32    /// The narrowest kind real code writes that admits every consumer of a
33    /// declaration in `declaring`: the parent when they all sit under it,
34    /// else the package; another package means `pub`, which is never
35    /// inferred.
36    pub fn narrowest(declaring: &Address, consumers: &[Address]) -> ReachKind {
37        let mut lca = declaring.clone();
38        for consumer in consumers {
39            match lca.lowest_common_ancestor(consumer) {
40                Some(shared) => lca = shared,
41                None => return ReachKind::Everyone,
42            }
43        }
44        if Some(&lca) == declaring.parent().as_ref() {
45            ReachKind::Parent
46        } else if &lca == declaring {
47            ReachKind::Declaring
48        } else {
49            ReachKind::Package
50        }
51    }
52
53    /// Whether every module `other` admits, this reach admits too.
54    pub fn covers(&self, other: &Reach) -> bool {
55        match (self, other) {
56            (Self::Everyone, _) => true,
57            (Self::Package(p), Self::Package(q)) => p == q,
58            (Self::Package(p), Self::Within(a)) => a.package() == p,
59            (Self::Within(a), Self::Within(b)) => b.starts_with(a),
60            _ => false,
61        }
62    }
63
64    /// Whether code in module `from` may name the declaration.
65    pub fn admits(&self, from: &Address) -> bool {
66        match self {
67            Self::Within(module) => from.starts_with(module),
68            Self::Package(package) => from.package() == package,
69            Self::Everyone => true,
70        }
71    }
72}
73
74impl std::fmt::Display for Reach {
75    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
76        match self {
77            Self::Within(module) if module.is_root() => write!(f, "{} (root)", module.package()),
78            Self::Within(module) => write!(f, "within {module}"),
79            Self::Package(package) => write!(f, "package {package}"),
80            Self::Everyone => f.write_str("everyone"),
81        }
82    }
83}
84
85#[cfg(test)]
86mod tests {
87    use super::*;
88
89    #[test]
90    fn reach_admits_by_prefix_package_or_everyone() {
91        let declaring = Address::new("k", ["a", "b"]);
92        let sibling = Address::new("k", ["a", "c"]);
93        let child = Address::new("k", ["a", "b", "d"]);
94        let elsewhere = Address::new("other", ["a", "b"]);
95        let private = Reach::of(ReachKind::Declaring, &declaring, None);
96        assert!(private.admits(&child) && !private.admits(&sibling));
97        let parent = Reach::of(ReachKind::Parent, &declaring, None);
98        assert!(parent.admits(&sibling) && !parent.admits(&Address::root("k")));
99        let package = Reach::of(ReachKind::Package, &declaring, None);
100        assert!(package.admits(&Address::root("k")) && !package.admits(&elsewhere));
101        assert!(Reach::of(ReachKind::Everyone, &declaring, None).admits(&elsewhere));
102        assert_eq!(
103            Reach::of(ReachKind::Parent, &Address::root("k"), None),
104            Reach::Within(Address::root("k"))
105        );
106    }
107}