Doc: dev-expr introduction

doc/Expr.adoc

@@ -22,15 +22,88 @@ Expressions calculator
 
 toc::[]
 
-#TODO: Work in progress#
+#TODO: Work in progress (last update on 2024/05/07, 07:15 am)#
 
 == Expr
 _Expr_ is a GO package capable of analysing, interpreting and calculating expressions.
 
+=== `dev-expr` test tool
+`dev-expr` is a simple program that can be used to evaluate expressions interactively. As its name suggests, it was created for testing purpose. In fact, beyond in additon to the automatic test suite based on the Go test framework, `dev-expr` provides an important aid for quickly testing of new features during their development.
+
+It cat work as a REPL, *R*ead-*E*xecute-*P*rint-*L*oop, or it can process expression acquired from files or standard input.
+
+The program in located in the _tools_ directory.
+Here are some examples of execution.
+
+.Run `dev-expr` in REPL mode and ask for help
+[source,shell]
+----
+# Assume the expr source directory. Type 'exit' or Ctrl+D to quit the program.
+
+[user]$ tools/expr -- Expressions calculator v1.6.1,2024/05/06 (celestino.amoroso@portale-stac.it)
+	Type help to get the list of command.
+	See also https://git.portale-stac.it/go-pkg/expr/src/branch/main/README.adoc
+
+>>> help
+--- REPL commands:
+        help -- Show command list
+          ml -- Enable/Disable multi-line output
+        mods -- List builtin modules
+         tty -- Enable/Disable ansi output <1>
+        exit -- Exit the program
+
+--- Command line options:
+    -b <builtin>       Import builtin modules.
+                       <builtin> can be a list of module names or a glob-pattern.
+                       Use the special value 'all' or the pattern '*' to import all modules.
+    -e <expression>    Evaluate <expression> instead of standard-input
+    -i                 Force REPL operation when all -e occurences have been processed
+    -h, --help, help   Show this help menu
+    -m, --modules      List all builtin modules
+    -p                 Print prefix form
+    -t                 Print tree form <2>
+----
+
+<1> Only available for single fraction values
+<2> Work in progress
+
+.REPL examples
+[source,shell]
+----
+[user]$ tools/expr -- Expressions calculator v1.6.1,2024/05/06 (celestino.amoroso@portale-stac.it)
+        Type help to get the list of command.
+        See also https://git.portale-stac.it/go-pkg/expr/src/branch/main/README.adoc
+>>> 2+3
+5
+>>> 2+3*(4-1.5)
+9.5
+>>> 0xFD + 0b1 + 0o1 <1>
+255
+>>> 1|2 + 2|3 <2>
+7|6
+>>> ml <3>
+>>> 1|2 + 2|3
+7
+-
+6
+>>> 1+2 but 5|2+0.5 <4>
+3
+>>> 1+2; 5|2+0.5 <5>
+3
+>>>
+----
+
+<1> Number bases: 0x = hexadecimal, 0o = octal, 0b = binary.
+<2> Fractions: numerator | denominator.
+<3> Activate multi-line output of fractions.
+<4> But operator, see <<_but_operator>>.
+<5> Multi-expression: the same result of the previous single expression but this it is obtained with two separated calculations.
 
 === Concepts and terminology
 #TODO#
 
+image::expression-diagram.png[]
+
 == Data types
 _Expr_ supports numerical, string, relational, boolean expressions, and mixed-type lists.
 
@@ -182,7 +255,7 @@ a=1; b=2; c=3; a+b+c    // returns 6
 ----
 
 === [blue]`but` operator
-[blue]`but` is an infixed operator. Its operands can be any type of expression. It evaluates the left expression first, then the right expression. The value of the right expression is the final result. Examples: [blue]`5 but 2` returns 2, [blue]`x=2*3 but x-1` returns 5.
+[blue]`but` is an infixed operator. Its operands can be expressions of any type. It evaluates the left expression first, then the right expression. The value of the right expression is the final result. Examples: [blue]`5 but 2` returns 2, [blue]`x=2*3 but x-1` returns 5.
 
 [blue]`but` is very similar to [blue]`;`. The only difference is that [blue]`;` can't be used inside parenthesis [blue]`(` and [blue]`)`.