Merge pull request #738 from vsbogd/add-var-scope-doc

Add explanation of the scope of the variables for minimal MeTTa

docs/minimal-metta.md

@@ -171,6 +171,35 @@ separate alternative.
 can collect the list of alternatives using `collapse-bind` filter them and
 return filtered items to the plan using `superpose-bind`.
 
+## Scope of a variable
+
+Each separately evaluated expression is a variable scope, and therefore variable names are treated as unique inside an expression.
+reason is that the whole expression is a variable scope. For example one can
+write the expression `(chain (unify $parent Bob () ()) $_ $parent)`. And value
+of the `$parent` is returned correctly.
+
+When a variable is passed as an argument to a function call and matched by a
+value then the value is assigned to the variable. If variable passed as an
+actual argument is matched by a formal argument variable then it is referenced
+by the formal argument variable. In this case the actual argument variable can
+receive a value outsides of its scope.
+
+For example the following code (written using MeTTa runner syntax) returns `B`:
+```
+(= (foo $b) (function (chain (unify B $b () ()) $_ (return ()))))
+!(chain (eval (foo $a)) $_ $a)
+```
+
+If two separate expressions in the space have a variable with the same
+name, but the variables reside in independent scopes, then the variables are different. Consider the
+following example:
+```
+(= (foo) (function (chain (unify A $a () ()) $_ (return ()))))
+!(chain (eval (foo)) $_ $a)
+```
+Here the value will not be assigned to the `$a` from the caller expression because
+each of the two variables has a different scope and they do not reference each other.
+
 # Examples
 
 Examples of the programs written using minimal MeTTa interpreter:
@@ -364,11 +393,6 @@ Nevertheless defining `eval` through `unify` requires rework of the grounded
 functions interface to allow calling them by executing `unify` instructions.
 Which is an interesting direction to follow.
 
-## Scope of variables
-
-Scope of the variable inside instructions is not described in this
-specification. It is a clear gap and one of the TODO items.
-
 ## Special matching syntax
 
 Sometimes it is convenient to change the semantics of the matching within a