From 1375f448a04adbfd2c41db113e8acf0ff429f2ef Mon Sep 17 00:00:00 2001
From: bakaq <bakaq@bakaq.net>
Date: Sun, 29 Sep 2024 23:21:18 -0300
Subject: [PATCH] LeafAnswer docs and success checking methods

---
 src/machine/parsed_results.rs | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/src/machine/parsed_results.rs b/src/machine/parsed_results.rs
index 3688bc97..ec3d4693 100644
--- a/src/machine/parsed_results.rs
+++ b/src/machine/parsed_results.rs
@@ -14,15 +14,47 @@ use super::{HeapCellValue, Number};
 /// Represents a leaf answer from a query.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum LeafAnswer {
+    /// A `true` leaf answer.
     True,
+    /// A `false` leaf answer.
+    ///
+    /// This means that there are no more answers for the query.
     False,
+    /// An exception leaf answer.
     Exception(PrologTerm),
+    /// A leaf answer with bindings and residual goals.
+    ///
+    /// Both bindings and residual goals can be empty.
     LeafAnswer {
         bindings: BTreeMap<String, PrologTerm>,
         residual_goals: Vec<PrologTerm>,
     },
 }
 
+impl LeafAnswer {
+    /// True if leaf answer failed.
+    ///
+    /// This gives [`false`] for exceptions.
+    pub fn failed(&self) -> bool {
+        match self {
+            LeafAnswer::False => true,
+            _ => false,
+        }
+    }
+
+    /// True if leaf answer may have succeeded.
+    ///
+    /// When a leaf answer has residual goals the success is conditional on the satisfiability of
+    /// the contraints they represent. This gives [`false`] for exceptions.
+    pub fn maybe_succeeded(&self) -> bool {
+        match self {
+            LeafAnswer::True => true,
+            LeafAnswer::LeafAnswer { .. } => true,
+            _ => false,
+        }
+    }
+}
+
 /// Represents a Prolog term.
 #[non_exhaustive]
 #[derive(Debug, Clone, PartialEq, Eq)]
-- 
2.54.0