docs/tests for Minimal MeTTa functions

src/canary/stdlib_mettalog.metta

@@ -92,7 +92,7 @@
 
 ; Public MinimalMeTTa
 (@doc eval
-  (@desc "Evaluates input atom, makes one step of the evaluation")
+  (@desc "Evaluates input Atom, performs one step of the evaluation. Empty results (Empty, ()) are removed from the result set. If no results are produced for a non-grounded function, eval returns NotReducible.")
   (@params (
     (@param "Atom to be evaluated, can be reduced via equality expression (= ...) or by calling a grounded function")))
   (@return "Result of evaluation"))
@@ -101,11 +101,11 @@
 
 ; Public MinimalMeTTa
 (@doc chain
-  (@desc "Evaluates first argument, binds it to the variable (second argument) and then evaluates third argument which contains (or not) mentioned variable")
+  (@desc "Evaluates first argument Atom, binds it to the Variable (second argument) and then evaluates third argument Template with Variable substituted in. When evaluation of the first Atom brings more than a single result, chain returns one instance of the Template expression for each result. The first argument Atom is only evaluated if it is part of the Minimal MeTTa specification; evaluation of non-Minimal MeTTa atoms can be controlled by wrapping in a call to eval (for one evaluation step) or metta (for full evaluation).")
   (@params (
     (@param "Atom to be evaluated")
     (@param "Variable")
-    (@param "Atom which will be evaluated at the end")))
+    (@param "Template which will be evaluated at the end with Variable substituted")))
   (@return "Result of evaluating third input argument"))
 (: chain (-> Atom Variable Atom Atom))
 ;; Implemented from Interpreters
@@ -132,7 +132,7 @@
 (= (if-unify-or-empty $a $b) (empty))
 
 
-;; Public MeTTa
+;; Public MinimalMeTTa
 (@doc cons-atom
   (@desc "Constructs an expression using two arguments")
   (@params (
@@ -143,7 +143,7 @@
 ;; Implemented from Interpreters
 ; AKA? (: cons (-> Atom Atom Atom))
 
-;; Public MeTTa
+;; Public MinimalMeTTa
 (@doc decons-atom
   (@desc "Works as a reverse to cons-atom function. It gets Expression as an input and returns it splitted to head and tail, e.g. (decons-atom (Cons X Nil)) -> (Cons (X Nil))")
   (@params (
@@ -153,26 +153,24 @@
 ;; Implemented from Interpreters
 ; AKA? (: decons (-> Atom Atom))
 
-;; Public MeTTa
+;; Public MinimalMeTTa
 (@doc collapse-bind
-  (@desc "Evaluates the Atom (first argument) and returns an expression which contains all alternative evaluations in a form (Atom Bindings). Bindings are represented in a form of a grounded atom.")
+  (@desc "Evaluates the Atom (first argument) and returns an expression which contains all alternative evaluations in a form (Atom Bindings). Bindings are represented in a form of a grounded atom { <var> <- <binding>, ... }. See also the complement superpose-bind. Note that, like chain, collapse-bind only evaluates Minimal Metta expressions. Evaluation of non-Minimal MeTTa atoms can be controlled by wrapping in a call to eval (for one evaluation step) or metta (for full evaluation).")
   (@params (
     (@param "Atom to be evaluated")))
   (@return "All alternative evaluations"))
-;; collapse-bind because `collapse` doesnt guarentee shared bindings
-(: collapse-bind (-> Atom Atom)) ; We specialize but leaving the old defs in case
+;; collapse-bind because `collapse` doesnt guarantee shared bindings
 (: collapse-bind (-> Atom Expression))
 ;; Implemented from Interpreters
 
-;; Public MeTTa
+;; Public MinimalMeTTa
 (@doc superpose-bind
-  (@desc "Complement to the collapse-bind. It takes result of collapse-bind (first argument) and returns only result atoms without bindings")
+  (@desc "Complement to the collapse-bind. It takes result of collapse-bind (first argument) and returns only result atoms without bindings. Primarily used with some filtering step on the collapse-bind results, i.e. collapse-bind -> <filter> -> superpose-bind.")
   (@params (
     (@param "Expression in form (Atom Binding)")))
   (@return "Non-deterministic list of Atoms"))
 ;; superpose-bind because `superpose` doesnt guarentee shared bindings
 (: superpose-bind (-> Expression Atom))
-(: superpose-bind (-> Atom Atom)) ; We specialize them but leaving the old defs in case
 ;; Implemented from Interpreters
 
 ; Helper Minimal Metta?

tests/baseline_compat/hyperon-mettalog_sanity/minimal_metta_tests.metta

@@ -0,0 +1,73 @@
+;; remove Empty result
+
+(= (returns-empty) Empty)
+(= (returns-empty) 1)
+(= (chain-to-empty) (returns-empty))
+
+!(assertEqualToResult (returns-empty) (1))
+!(assertEqualToResult (eval (returns-empty)) (1))
+!(assertEqualToResult (chain-to-empty) (1))
+!(assertEqualToResult (eval (chain-to-empty)) (1))
+!(assertEqualToResult (chain (eval (returns-empty)) $x (quote $x)) ((quote 1) (quote Empty)))
+!(assertEqualToResult (chain (eval (chain-to-empty)) $x (quote $x)) ((quote (returns-empty))))
+
+;; include empty expression ()
+
+(= (returns-empty-expression) ())
+(= (returns-empty-expression) 1)
+(= (chain-to-empty-expression) (returns-empty-expression))
+
+!(assertEqualToResult (returns-empty-expression) (1 ()))
+!(assertEqualToResult (eval (returns-empty-expression)) (1 ()))
+!(assertEqualToResult (chain-to-empty-expression) (1 ()))
+!(assertEqualToResult (eval (chain-to-empty-expression)) (1 ()))
+!(assertEqualToResult (chain (eval (returns-empty-expression)) $x (quote $x)) ((quote 1) (quote ())))
+!(assertEqualToResult (chain (eval (chain-to-empty-expression)) $x (quote $x)) ((quote (returns-empty-expression))))
+
+;; return original form for NotReducible
+
+(= (returns-not-reducible) NotReducible)
+(= (returns-not-reducible)  1)
+(= (chain-to-not-reducible) (returns-not-reducible))
+
+!(assertEqualToResult (returns-not-reducible)  (1 (returns-not-reducible)))
+!(assertEqualToResult (chain-to-not-reducible)  (1 (returns-not-reducible)))
+!(assertEqualToResult (eval (returns-not-reducible))  (1 (eval (returns-not-reducible))))
+!(assertEqualToResult (eval (chain-to-not-reducible))  (1 (returns-not-reducible)))
+!(assertEqualToResult (chain (eval (returns-not-reducible)) $x (quote $x)) ((quote 1) (quote NotReducible)))
+!(assertEqualToResult (chain (eval (chain-to-not-reducible)) $x (quote $x)) ((quote (returns-not-reducible))))
+
+;; collapse-bind operates on Minimal MeTTa
+
+(= (bar A) (input A))
+(= (bar B) (input B))
+(= (foo $x) (bar $x))
+
+!(assertEqualToResult (chain (collapse-bind (foo $x)) $a (quote $a)) ((quote (((foo $x) {  })))))
+!(assertEqualToResult (chain (collapse-bind (eval (foo $x))) $a (quote $a)) ((quote (((bar $x) {  })))))
+!(assertEqualToResult (chain (collapse-bind (metta (foo $x) %Undefined% &self)) $a (quote $a)) ((quote (((input B) { $x <- B }) ((input A) { $x <- A })))))
+
+;; superpose-bind complements collapse-bind
+
+!(assertEqualToResult (chain (collapse-bind (foo $x)) $a 
+                            (chain (superpose-bind $a) $b (quote $b))) 
+                    ((quote (foo $x))))
+!(assertEqualToResult (chain (collapse-bind (eval (foo $x))) $a 
+                            (chain (superpose-bind $a) $b (quote $b))) 
+                    ((quote (bar $x))))
+!(assertEqualToResult (chain (collapse-bind (metta (foo $x) %Undefined% &self)) $a 
+                            (chain (superpose-bind $a) $b (quote $b))) 
+                    ((quote (input B)) (quote (input A))))
+
+;; metta handles type
+
+(= (foobar) 1)
+(= (foobar) "a")
+(= (chain-to-foobar) (foobar))
+
+!(assertEqualToResult (metta (foobar) Number &self) (1))
+!(assertEqualToResult (metta (foobar) String &self) ("a"))
+!(assertEqualToResult (collapse-bind (metta (foobar) $type &self)) ((1 { $type <- Number }) ("a" { $type <- String })))
+!(assertEqualToResult (metta (chain-to-foobar) Number &self) (1))
+!(assertEqualToResult (metta (chain-to-foobar) String &self) ("a"))
+!(assertEqualToResult (collapse-bind (metta (chain-to-foobar) $type &self)) ((1 { $type <- Number }) ("a" { $type <- String })))