Determine exhaustiveness as When instead of bool.

This change uses `BoundaryTerm` to query disjunctive terms and determine
not only if a token is or isn't exhaustive but also if it is _sometimes_
exhaustive. `Program::is_exhaustive` now returns `When`, much like
`has_root`.

Author: olson-sean-k

src/lib.rs

@@ -201,7 +201,7 @@ pub trait Program<'t>: Pattern<'t, Error = Infallible> {
     /// # Examples
     ///
     /// Text variance can be used to determine if a pattern can be trivially represented by an
-    /// equivalent path using platform file system APIs.
+    /// equivalent native path using platform file system APIs.
     ///
     /// ```rust
     /// use std::path::Path;
@@ -220,22 +220,24 @@ pub trait Program<'t>: Pattern<'t, Error = Infallible> {
     /// A glob expression that begins with a separator `/` has a root, but less trivial patterns
     /// like `/**` and `</root:1,>` can also root an expression. Some `Program` types may have
     /// indeterminate roots and may match both candidate paths with and without a root. In this
-    /// case, this functions returns [`Sometimes`] (indeterminate).
+    /// case, this functions returns [`Sometimes`].
     ///
     /// [`Sometimes`]: crate::query::When::Sometimes
     fn has_root(&self) -> When;
 
-    /// Returns `true` if the pattern is exhaustive.
+    /// Describes when the pattern matches candidate paths exhaustively.
     ///
     /// A glob expression is exhaustive if, given a matched candidate path, it necessarily matches
-    /// any and all sub-trees of that path. For example, glob expressions that end with a tree
-    /// wildcard like `.local/**` are exhaustive, but so are less trivial expressions like `<<?>/>`
-    /// and `<doc/<*/:3,>>`. This can be an important property when determining what directory
-    /// trees to read or which files and directories to select with a pattern.
+    /// any and all sub-trees of that path. For example, given the pattern `.local/**` and the
+    /// matched path `.local/bin`, any and all paths beneath `.local/bin` also match the pattern.
     ///
-    /// Note that this applies to the **pattern** and **not** to a particular match. It is possible
-    /// for a particular match against a **non**exhaustive pattern to be exhaustive.
-    fn is_exhaustive(&self) -> bool;
+    /// Patterns that end with tree wildcards are more obviously exhaustive, but less trivial
+    /// patterns like `<<?>/>`, `<doc/<*/:3,>>`, and `{a/**,b/**}` can also be exhaustive. Patterns
+    /// with alternations may only be exhaustive for some matched paths. In this case, this
+    /// function returns [`Sometimes`].
+    ///
+    /// [`Sometimes`]: crate::query::When::Sometimes
+    fn is_exhaustive(&self) -> When;
 }
 
 /// General errors concerning [`Program`]s.
@@ -758,7 +760,7 @@ impl<'t> Program<'t> for Glob<'t> {
         self.tree.as_ref().as_token().has_root()
     }
 
-    fn is_exhaustive(&self) -> bool {
+    fn is_exhaustive(&self) -> When {
         self.tree.as_ref().as_token().is_exhaustive()
     }
 }
@@ -817,7 +819,7 @@ impl<'t> Program<'t> for Any<'t> {
         self.tree.as_ref().as_token().has_root()
     }
 
-    fn is_exhaustive(&self) -> bool {
+    fn is_exhaustive(&self) -> When {
         self.tree.as_ref().as_token().is_exhaustive()
     }
 }

src/query.rs

@@ -97,14 +97,14 @@ pub enum Variance<T, B> {
 impl<T, B> Variance<T, B> {
     pub fn invariant(self) -> Option<T> {
         match self {
-            Variance::Invariant(invariance) => Some(invariance),
+            Variance::Invariant(invariant) => Some(invariant),
             _ => None,
         }
     }
 
     pub fn variant(self) -> Option<B> {
         match self {
-            Variance::Variant(variance) => Some(variance),
+            Variance::Variant(bound) => Some(bound),
             _ => None,
         }
     }
@@ -114,8 +114,8 @@ impl<T, B> Variance<T, B> {
     /// Produces a new `Variance` that contains a reference `self`, leaving `self` in place.
     pub fn as_ref(&self) -> Variance<&T, &B> {
         match self {
-            Variance::Invariant(ref invariance) => Variance::Invariant(invariance),
-            Variance::Variant(ref variance) => Variance::Variant(variance),
+            Variance::Invariant(ref invariant) => Variance::Invariant(invariant),
+            Variance::Variant(ref bound) => Variance::Variant(bound),
         }
     }
 
@@ -263,6 +263,22 @@ impl When {
     pub fn is_never(&self) -> bool {
         matches!(self, When::Never)
     }
+
+    /// Returns `true` if the truth value is [`Always`] or [`Sometimes`].
+    ///
+    /// [`Always`]: crate::query::When::Always
+    /// [`Sometimes`]: crate::query::When::Sometimes
+    pub fn is_maybe_true(&self) -> bool {
+        !self.is_never()
+    }
+
+    /// Returns `true` if the truth value is [`Never`] or [`Sometimes`].
+    ///
+    /// [`Never`]: crate::query::When::Never
+    /// [`Sometimes`]: crate::query::When::Sometimes
+    pub fn is_maybe_false(&self) -> bool {
+        !self.is_always()
+    }
 }
 
 impl From<bool> for When {

src/token/mod.rs

@@ -569,21 +569,16 @@ impl<'t, A> Token<'t, A> {
         }
     }
 
-    // TODO: Exhaustiveness should be expressed with `When` rather than `bool`. In particular,
-    //       alternations may _sometimes_ be exhaustive.
     // TODO: There is a distinction between exhaustiveness of a glob and exhaustiveness of a match
     //       (this is also true of other properties). The latter can be important for performance
     //       optimization, but may also be useful in the public API (perhaps as part of
     //       `MatchedText`).
-    // NOTE: False positives in this function may cause logic errors and are completely
-    //       unacceptable. The discovery of a false positive here almost cetainly indicates a
-    //       serious bug. False positives in negative patterns cause matching to incorrectly
-    //       discard directory trees in the `FileIterator::not` combinator.
-    pub fn is_exhaustive(&self) -> bool {
+    // NOTE: False positives in this function cause negated pattern to incorrectly discard
+    //       directory trees in the `FileIterator::not` combinator.
+    pub fn is_exhaustive(&self) -> When {
         self.fold(TreeExhaustiveness)
-            .map(Finalize::finalize)
             .as_ref()
-            .map_or(false, Variance::is_exhaustive)
+            .map_or(When::Never, BoundaryTerm::is_exhaustive)
     }
 }
 

src/token/variance/invariant/mod.rs

@@ -3,6 +3,7 @@ mod text;
 
 use std::num::NonZeroUsize;
 
+use crate::query::When;
 use crate::token::variance::natural::{
     define_natural_invariant, BoundedVariantRange, OpenedUpperBound,
 };
@@ -147,8 +148,17 @@ impl TokenVariance<Depth> {
 }
 
 impl BoundaryTerm<Depth> {
-    pub fn is_exhaustive(&self) -> bool {
-        self.clone().finalize().is_exhaustive()
+    pub fn is_exhaustive(&self) -> When {
+        match self {
+            BoundaryTerm::Conjunctive(SeparatedTerm(_, ref term)) => term.is_exhaustive().into(),
+            BoundaryTerm::Disjunctive(ref term) => term
+                .branches()
+                .map(AsRef::as_ref)
+                .map(TokenVariance::<Depth>::is_exhaustive)
+                .map(When::from)
+                .reduce(When::certainty)
+                .unwrap_or(When::Never),
+        }
     }
 }
 

src/token/variance/invariant/term.rs

@@ -142,6 +142,10 @@ where
     {
         DisjunctiveTerm(self.0.into_iter().map(f).collect())
     }
+
+    pub fn branches(&self) -> impl '_ + Iterator<Item = &'_ T> {
+        self.0.iter()
+    }
 }
 
 impl<T> Conjunction for DisjunctiveTerm<T>
@@ -290,6 +294,18 @@ impl Conjunction for Termination {
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
 pub struct SeparatedTerm<T>(pub Termination, pub T);
 
+impl<T> AsMut<T> for SeparatedTerm<T> {
+    fn as_mut(&mut self) -> &mut T {
+        &mut self.1
+    }
+}
+
+impl<T> AsRef<T> for SeparatedTerm<T> {
+    fn as_ref(&self) -> &T {
+        &self.1
+    }
+}
+
 impl<T, U> Conjunction<SeparatedTerm<U>> for SeparatedTerm<T>
 where
     SeparatedTerm<T>: Finalize<Output = T>,