Merge pull request #193 from AdrickTench/main

more tests/docs - load functions, save-space!, rust, rust!

src/canary/stdlib_mettalog.metta

@@ -1353,7 +1353,7 @@
 
 ;; Public MeTTa
 (@doc import!
-  (@desc "Imports module using its relative path (second argument) and binds it to the token (first argument) which will represent imported atomspace. If first argument is &self then everything will be imported to current atomspace")
+  (@desc "Imports module using its relative path (second argument) and binds it to the token (first argument) which will represent imported atomspace. If first argument is &self then everything will be imported to current atomspace. The source is imported only the first time import! is called. Can load Python code (.py) or MeTTa (.metta); if ambiguous, assumes Python.")
   (@params (
     (@param "Symbol, which is turned into the token for accessing the imported module")
     (@param "Module name")))
@@ -1363,7 +1363,7 @@
 
 ;; Public MeTTa
 (@doc include
-  (@desc "Works just like import! but with &self as a first argument. So everything from input file will be included in the current atomspace and evaluated")
+  (@desc "Works just like include! but with &self as a first argument. So everything from input file will be included in the current atomspace and evaluated")
   (@params (
     (@param "Name of metta script to import")))
   (@return "Unit atom"))
@@ -1372,7 +1372,7 @@
 
 ;; Public MeTTa
 (@doc include!
-  (@desc "Works just like import!. So everything from input file will be included in the current atomspace and evaluated")
+  (@desc "Everything from input file will be included in the current atomspace and evaluated, as if it were being evaluated at the REPL. Unlike import!, the source is evaluated every time include! is called.")
   (@params (
     (@param "Space")
     (@param "Filename")))
@@ -1827,7 +1827,7 @@
 
 ;; Public MeTTaLog
 (@doc load-file!
-  (@desc "Loads the contents of Filename into Space, returning () if successful.")
+  (@desc "Loads the contents of Filename into Space, returning () if successful. Can load Python code (.py) or MeTTa (.metta); if ambiguous, assumes MeTTa. Like import! but favors MeTTa over Python when the file type is ambiguous.")
   (@params (
     (@param "Space")
     (@param "Filename")))
@@ -1836,9 +1836,52 @@
 
 ;; Public MeTTa
 (@doc load-ascii
-  (@desc "Loads the contents of Filename into Space, returning () if successful. Assumes the file is an ASCII file.")
+  (@desc "Loads the contents of Filename into Space, returning () if successful. Assumes the file is an ASCII file. Works like include!.")
   (@params (
     (@param "Space")
     (@param "Filename")))
   (@return "Expression"))
 (: load-ascii (-> hyperon::space::DynSpace String Expression))
+
+;; Public MeTTa
+(@doc transfer!
+  (@desc "Loads the contents of Filename into &self, as include. Returns () if successful, throws an exception otherwise.")
+  (@params (
+    (@param "Filename")))
+  (@return "Expression"))
+(: transfer! (-> String Expression))
+
+;; Public MeTTa
+(@doc save-space!
+  (@desc "Writes the contents of Space into Filename, returning () if successful.")
+  (@params (
+    (@param "Space")
+    (@param "Filename")))
+  (@return "Expression"))
+(: save-space! (-> hyperon::space::DynSpace String Expression))
+
+;; MeTTaLog Debugging
+(@doc rtrace!
+  (@desc "Fully evaluates input Atom, providing a complete trace of the evaluation.")
+  (@params (
+    (@param "Atom to be evaluated")))
+  (@return "Result of evaluation"))
+(: rtrace! (-> Atom Atom))
+
+;; Public MeTTaLog
+
+(@doc rust
+  (@desc "Interface with the rust / Hyperon MeTTa implementation. Enters Atom into rust atomspace. If Atom is evaluated (i.e. by being of the form !<atom>), returns the result of evaluation. See also rust!.")
+  (@params (
+    (@param "Atom to be entered into the space")))
+  (@return "Result of entering Atom into the space"))
+(: rust (-> Atom Atom))
+
+;; Public MeTTaLog
+
+(@doc rust!
+  (@desc "Like rust but evaluates the atom rather than entering into the space. (rust! <atom>) and (rust !<atom>) are identical.")
+  (@params (
+    (@param "Atom to be evaluated")))
+  (@return "Result of evaluation"))
+(: rust! (-> Atom Atom))

tests/baseline_compat/hyperon-mettalog_sanity/output_load_tests.metta

@@ -60,3 +60,20 @@
                       ("(bar 1)" "(bar 2)"))
 !(assertEqualToResult (let $f (filename) (load-file! &self $f)) (()))
 !(assertEqualToResult (match &self (bar $x) $x) (1 2))
+
+;; test save-space!
+
+!(bind! &gen-space (new-space))
+!(bind! &load-space (new-space))
+
+!(add-atom &gen-space (likes John Jane))
+!(add-atom &gen-space (= (foo $x) (+ $x 1)))
+
+!(assertEqualToResult (match &gen-space (likes $x $y) ($x $y)) ((John Jane)))
+!(assertEqualToResult (metta (foo 1) Number &new-space) (2))
+
+!(assertEqualToResult (save-space! &gen-space "save-space-test.tmp") (()))
+!(assertEqualToResult (load-file! &load-space "save-space-test.tmp") (()))
+
+!(assertEqualToResult (match &load-space (likes $x $y) ($x $y)) ((John Jane)))
+!(assertEqualToResult (metta (foo 1) Number &load-space) (2))