Block scanner extension

Author: promicsw

FexOverview.md

@@ -0,0 +1,37 @@
+# Flow Expressions Overview
+
+A flow expression can implement just about any type of *flow logic*. Mainly for, but not limited to, **Parser** and **DSL** (domain specific language) construction. 
+
+Flow expressions are constructed from the various FexElements (*building blocks*) via a fluent API. These FexElements define the logical flow and operation of the expression in a very readable and maintainable format. 
+
+> A running Flow Expression operates on a user supplied **Context**, which is any environment that manages and provides input/content/state.
+>
+> For a Parser, the context would be a **Scanner** that manages text scanning and provides <i>Tokens</i> to operate on.<br/> 
+>
+> A comprehensive [FexScanner](Docs/FexScannerExt.md) is provided (derived from *ScriptScanner* in the [Scanners](https://github.com/PromicSW/scanners) repo/library) but you can roll your own if required. 
+
+## FexElements perform several types of functions:
+
+> Please see the [Fex Element reference](Docs/FexElementsRef.md) section for full details.<br>
+> Also [FexScanner context extensions](Docs/FexScannerExt.md) for extensions specific to the FexScanner context.
+
+- **Operators (Op):** Perform a operation on the context, returning a success status (true/false). 
+    - Certain Op's produce and record a value for later use via one of the Action elements.
+    - An Op can operate on the context directly, but typically *Operator Extension methods* are defined to create re-usable (and more readable) operators specific to the context used.
+    - There is also a facility to attach Pre-Operations to operators (e.g skip spaces when scanning etc.)
+- **Sequence(Seq):** A sequence is the primary construct used in flow expressions and defines a series of steps (1..n) to complete: 
+    - A step is any FexElement.
+    - All steps is a sequence must complete else the sequence fails.
+    - A step(s) may be optional and there are several rules governing this.
+- **Flow Control:** These elements control the flow of an expression:
+    - Opt: Optional sequence.
+    - OneOf: One of a set of sequences must pass.
+    - NotOneOf: Inverse of OneOf.
+    - Rep...: Repeat sequences.
+
+- **Actions:** Perform actions based on the current state of the production to check values or perform any other actions required on the context:
+    - Actions don't affect the validity of a sequence.
+    - There are general actions and those that operate on a value recorded by and operator.
+    - An Action can operate on the context directly, but typically *Action Extension methods* are defined to create re-usable (and more readable) actions specific to the context used.
+- **Error reporting:** Elements for error handling and reporting.
+- **Tracing:** Tracing elements primarily for debugging purposes.

FexSampleSet/Program.cs

@@ -8,6 +8,9 @@
 
 RunSamplesFex();
 
+//ExpressionEval();
+//ExpressionEval("5");
+
 
 void RunSamples() {
 
@@ -58,43 +61,24 @@ void RunSamplesFex() {
 
     string val = "";
 
+    // FexNoContext is just an empty class since we don't do any scanning here.
     new FlowExpression<FexNoContext>()
         .Rep0N(r => r
-        .Act(c => Console.WriteLine("Run Sample:"))
-        .RepAct(samples.Count, (c, i) => Console.WriteLine($"  {i + 1} - {samples[i].Name}"))
-        .Act(c => Console.Write("  Blank to Exit\r\n> "))
-        .Op(o => !string.IsNullOrEmpty(val = Console.ReadLine()))
-        .Act(c => {
-            Console.Clear();
-            if (int.TryParse(val, out int m)) {
-                if (m > 0 && m <= samples.Count) {
-                    Console.WriteLine($"Run: {samples[m - 1].Name}");
-                    samples[m - 1].Run();
-                    Console.WriteLine();
+            .Act(c => Console.WriteLine("Run Sample:"))
+            .RepAct(samples.Count, (c, i) => Console.WriteLine($"  {i + 1} - {samples[i].Name}"))
+            .Act(c => Console.Write("  Blank to Exit\r\n> "))
+            .Op(o => !string.IsNullOrEmpty(val = Console.ReadLine()))
+            .Act(c => {
+                Console.Clear();
+                if (int.TryParse(val, out int m)) {
+                    if (m > 0 && m <= samples.Count) {
+                        Console.WriteLine($"Run: {samples[m - 1].Name}");
+                        samples[m - 1].Run();
+                        Console.WriteLine();
+                    }
                 }
-            }
-        })
-    ).Run(new FexNoContext());
-
-    //var fex = new FlowExpression<FexNoContext>();
-
-    //fex.Rep0N(r => r
-    //    .Act(c => Console.WriteLine("Run Sample:"))
-    //    .RepAct(samples.Count, (c, i) => Console.WriteLine($"  {i + 1} - {samples[i].Name}"))
-    //    .Act(c => Console.Write("  Blank to Exit\r\n> "))
-    //    .Op(o => !string.IsNullOrEmpty(val = Console.ReadLine()))
-    //    .Act(c => {
-    //        Console.Clear();
-    //        if (int.TryParse(val, out int m)) {
-    //            if (m > 0 && m <= samples.Count) {
-    //                Console.WriteLine($"Run: {samples[m - 1].Name}");
-    //                samples[m - 1].Run();
-    //                Console.WriteLine();
-    //            }
-    //        }
-    //    })
-    //).Run(new FexNoContext());
-
+            })
+        ).Run(new FexNoContext());
 }
 
 // QuickStart sample 
@@ -110,13 +94,13 @@ void QuickStart() {
      *   - number: 4 digits
      */
 
-    var fex = new FlowExpression<FexScanner>();  // Flow Expression using FexScanner
-    string dcode = "", acode = "", number = "";  // Will record the values in here
+    var fex = new FlowExpression<FexScanner>();  // Flow Expression using FexScanner.
+    string dcode = "", acode = "", number = "";  // Will record values in here.
 
     // Build the flow expression with 'Axiom' tnumber:
     var tnumber = fex.Seq(s => s
         .Ch('(').OnFail("( expected")
-        .Rep(3, -1, r => r.Digit(v => dcode += v)).OnFail("at least 3 digit dialing code expected")
+        .Rep(3, -1, r => r.Digit(v => dcode += v)).OnFail("3+ digit dialing code expected")
         .Ch(')').OnFail(") expected")
         .Sp()
         .Rep(3, r => r.Digit(v => acode += v)).OnFail("3 digit area code expected")
@@ -158,22 +142,20 @@ void DemoSimpleScanner() {
 }
 
 // Expression Evaluation - using FexParser
-void ExpressionEval() {
+void ExpressionEval(string calc = "9 - (5.5 + 3) * 6 - 4 / ( 9 - 1 )") {
 
     /*
      * Expression Grammar:
-     * expression     => factor ( ( '-' | '+' ) factor )* ;
-     * factor         => unary ( ( '/' | '*' ) unary )* ;
-     * unary          => ( '-' ) unary | primary ;
-     * primary        => NUMBER | "(" expression ")" ;
+     * expression => factor ( ( '-' | '+' ) factor )* ;
+     * factor     => unary ( ( '/' | '*' ) unary )* ;
+     * unary      => ( '-'  unary ) | primary ;
+     * primary    => NUMBER | "(" expression ")" ;
     */
 
-    // Number Stack for calculations
+    // Number Stack for calculations:
     Stack<double> numStack = new Stack<double>();
 
-    var expr1 = "9 - (5.5 + 3) * 6 - 4 / ( 9 - 1 )";
-
-    Console.WriteLine($"Evaluating expression: {expr1}");
+    Console.WriteLine($"Calculate: {calc}");
 
     var fex = new FlowExpression<FexScanner>();  
 
@@ -197,20 +179,20 @@ void ExpressionEval() {
         .OneOf(o => o
             .Seq(s => s.Ch('-').Ref("unary").Act(a => numStack.Push(-numStack.Pop())))
             .Ref("primary")
-         ).OnFail("Primary expected"));
+         ));
 
     var primary = fex.Seq(s => s.RefName("primary")
         .OneOf(o => o
             .Seq(e => e.Ch('(').Fex(expr).Ch(')').OnFail(") expected"))
             .Seq(s => s.NumDecimal(n => numStack.Push(n)))
-         ));
+         ).OnFail("Primary expected"));
 
     var exprEval = fex.Seq(s => s.GlobalPreOp(c => c.SkipSp()).Fex(expr).IsEos().OnFail("invalid expression"));
 
-    var scn = new FexScanner(expr1);
+    var scn = new FexScanner(calc);
 
     Console.WriteLine(exprEval.Run(scn) 
-        ? $"Passed = {numStack.Pop():F4}" 
+        ? $"Answer = {numStack.Pop():F4}" 
         : scn.ErrorLog.AsConsoleError("Expression Error:"));
 }
 
@@ -244,14 +226,14 @@ void ExpressionREPL() {
         .OneOf(o => o
             .Seq(s => s.Ch('-').Ref("unary").Act(a => numStack.Push(-numStack.Pop())))
             .Ref("primary")
-         ).OnFail("Primary expected"));
+         ));
 
     var primary = fex.Seq(s => s.RefName("primary")
         .OneOf(o => o
             .Seq(e => e.Ch('(').Fex(expr).Ch(')').OnFail(") expected"))
             .Seq(s => s.NumDecimal(n => numStack.Push(n)))
             .Seq(s => s.Ch('a').Act(c => numStack.Push(ans)))  // a is previous answer
-         ));
+         ).OnFail("Primary expected"));
 
     var exprEval = fex.Seq(s => s.GlobalPreOp(c => c.SkipSp()).Fex(expr).IsEos().OnFail("invalid expression"));
 

FlowExpressions.sln

@@ -15,6 +15,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Docs", "Docs", "{16EDBBE2-1
 	ProjectSection(SolutionItems) = preProject
 		Docs\CustomScanner.md = Docs\CustomScanner.md
 		Docs\FexElementsRef.md = Docs\FexElementsRef.md
+		FexOverview.md = FexOverview.md
 		Docs\FexScannerExt.md = Docs\FexScannerExt.md
 	EndProjectSection
 EndProject