Doc updates

Author: promicsw

Docs/FexElementsRef.md

@@ -12,9 +12,13 @@ Flow expressions are constructed from the various **FexElements** (*building blo
 
 ## 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 as context.
+| Detailed References: |
+| :------------------- |
+| [Fex Element reference](Docs/FexElementsRef.md): describes each FexElement type with examples. |
+| [FexScanner context extensions](Docs/FexScannerExt.md): describes all the context extensions for the supplied FexScanner. |
+| [Custom Scanner](Docs/CustomScanner.md): a tutorial/example of a custom scanner and context extensions. |
 
+### FexElement Types:
 - **Operators (Op):** Perform a operation on the context, returning a success status (true/false). 
     - An operator is implemented via a `Func<context, bool>` delegate which can either operate on the context and/or the *closure* environment.
     - For example: if the context is a scanner then the Op would typically perform one of the scanning methods/functions.
@@ -24,7 +28,7 @@ Flow expressions are constructed from the various **FexElements** (*building blo
 - **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 (see reference section).
+    - Steps may be optional and there are several rules governing this (see reference section).
 - **Flow Control:** These elements control the flow of an expression:
     - Opt: Optional sequence.
     - OneOf: One of a set of sequences must pass.
@@ -48,18 +52,16 @@ using Psw.FlowExpressions;
 
 void RefExpressionEval(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 Grammar:
+    //   expression => factor ( ( '-' | '+' ) factor )* ;
+    //   factor     => unary ( ( '/' | '*' ) unary )* ;
+    //   unary      => ( '-'  unary ) | primary ;
+    //   primary    => NUMBER | "(" expression ")" ;
 
     // Number Stack for calculations:
     Stack<double> numStack = new Stack<double>();
 
-    // The FlowExpression object used to create FexElements with FexScanner as the context:
+    // The FlowExpression factory used to create FexElements with FexScanner as the context:
     var fex = new FlowExpression<FexScanner>();
 
     // Define the main expression production, which returns a Sequence element:
@@ -92,7 +94,7 @@ void RefExpressionEval(string calc = "9 - (5.5 + 3) * 6 - 4 / ( 9 - 1 )")
             .Seq(s => s.Ch('*').Ref("unary").Act(c => numStack.Push(numStack.Pop() * numStack.Pop())))
 
             // If we have a '/' run unary, check for division by zero and then divide the top two values on the stack:
-            // Note again the stack is in reverse order.
+            // o Note again the stack is in reverse order.
             .Seq(s => s.Ch('/').Ref("unary")
                        .Op(c => numStack.Peek() != 0).OnFail("Division by 0") // Trap division by 0 and report as error.
                        .Act(c => numStack.Push(1 / numStack.Pop() * numStack.Pop())))
@@ -143,10 +145,67 @@ void RefExpressionEval(string calc = "9 - (5.5 + 3) * 6 - 4 / ( 9 - 1 )")
     var scn = new FexScanner(calc);
 
     // Run the Axiom with the scanner which returns true/false:
-    // o If valid display the answer = top value on the stack.
+    // o If valid display the answer (= top value on the stack).
     // o Else display the error logged in the scanner's shared ErrorLog.
     Console.WriteLine(exprEval.Run(scn)
         ? $"Answer = {numStack.Pop():F4}"
         : scn.ErrorLog.AsConsoleError("Expression Error:"));
 }
+```
+
+### Sequence chart:
+```mermaid
+graph LR
+  subgraph "Seq (Sequence)" 
+    direction LR
+    A[Step 1] --> B[Step 2] -.-> C[Step n];
+  end
+```
+
+### Opt(ional) chart:
+```mermaid
+graph LR
+  subgraph "Opt (Optional)" 
+    A[Seq]
+  end
+```
+
+### One of chart:
+```mermaid
+graph LR
+  subgraph OneOf
+    direction LR
+    A[Seq 1] -->|or| B[Seq 2] -.->|or| C[Seq 3];
+  end
+```
+
+### Opt One of chart:
+```mermaid
+graph LR
+  subgraph "Opt (Optional)" 
+    subgraph OneOf
+      direction LR
+      A[Seq 1] -->|or| B[Seq 2] -.->|or| C[Seq 3];
+    end
+  end
+```
+
+### Repeat:
+```mermaid
+graph LR
+  subgraph "Rep (Repeat: min, max)"
+    direction LR
+    A[Seq];
+  end
+```
+
+### RepeatOneOf:
+```mermaid
+graph LR
+  subgraph "Rep (Repeat: min, max)"
+    subgraph OneOf
+      direction LR
+      A[Seq 1] -->|or| B[Seq 2] -.->|or| C[Seq 3];
+  end
+  end
 ```

Docs/FexOverview.md

@@ -0,0 +1,65 @@
+# Flow Expression Graphs
+
+### Class Diagram
+```mermaid
+classDiagram
+  FexElement <|-- Seq
+  FexElement <|-- Opt
+  FexElement <|-- OneOf
+  FexElement <|-- OptOneOf
+  FexElement <|-- Rep
+  FexElement <|-- RepOneOf
+```
+
+### Sequence:
+```mermaid
+graph LR
+  subgraph "Seq (Sequence)" 
+    direction LR
+    A[FexElement 1] --> B[FexElement 2] -.-> C[FexElement n];
+  end
+```
+
+### Optional:
+```mermaid
+graph LR
+  subgraph "Opt (Optional)" 
+    A[Seq]
+  end
+```
+
+### OneOf:
+```mermaid
+graph LR
+  subgraph OneOf
+    direction LR
+    A[Seq 1] -->|or| B[Seq 2] -.->|or| C[Seq 3];
+  end
+```
+
+### OptOneOf:
+```mermaid
+graph LR
+  subgraph OptOneOf
+    direction LR
+    A[Seq 1] -->|or| B[Seq 2] -.->|or| C[Seq 3];
+  end
+```
+
+### Repeat:
+```mermaid
+graph LR
+  subgraph "Rep (Repeat: min, max)"
+    direction LR
+    A[Seq];
+  end
+```
+
+### RepOneOf:
+```mermaid
+graph LR
+  subgraph "RepOneOf (min, max)"
+    direction LR
+    A[Seq 1] -->|or| B[Seq 2] -.->|or| C[Seq 3];
+  end
+```

FexGraphs.md

@@ -12,14 +12,17 @@ namespace FexExampleSet
     /// </summary>
     public static class FexBuilderExt
     {
-        public static FexBuilder<T> CTrace<T>(this FexBuilder<T> b, string text) 
-            => b.Trace((c, res) => Console.WriteLine($"{text} : {res}"));
+        public static FexBuilder<T> CTrace<T>(this FexBuilder<T> b, string text)
+           => b.Trace((c) => Console.WriteLine($"{text}"));
 
-        public static FexBuilder<T> CTrace<T>(this FexBuilder<T> b, Func<T, string> trace) 
-            => b.Trace((c, res) => Console.WriteLine($"{trace(c)} : {res}"));
+        public static FexBuilder<T> CTraceOp<T>(this FexBuilder<T> b, string text) 
+            => b.TraceOp((c, res) => Console.WriteLine($"{text} : {res}"));
 
-        public static FexBuilder<T> CTrace<T>(this FexBuilder<T> b, Func<T, object, string> trace)
-            => b.Trace((c, v, res) => Console.WriteLine($"{trace(c, v)} : {res}"));
+        public static FexBuilder<T> CTraceOp<T>(this FexBuilder<T> b, Func<T, string> trace) 
+            => b.TraceOp((c, res) => Console.WriteLine($"{trace(c)} : {res}"));
+
+        public static FexBuilder<T> CTraceOp<T>(this FexBuilder<T> b, Func<T, object, string> trace)
+            => b.TraceOp((c, v, res) => Console.WriteLine($"{trace(c, v)} : {res}"));
     }
 
 }

FexSampleSet/FexBuilderExt.cs

@@ -7,6 +7,10 @@
     <Nullable>enable</Nullable>
   </PropertyGroup>
 
+  <ItemGroup>
+    <Compile Remove="FexBuilderExt.cs" />
+  </ItemGroup>
+
   <ItemGroup>
     <ProjectReference Include="..\Psw.FlowExpressions\Psw.FlowExpressions.csproj" />
   </ItemGroup>

FexSampleSet/FexSampleSet.csproj

@@ -7,6 +7,7 @@
 using Psw.FlowExpressions;
 
 RunSamplesFex();
+//TraceExpressionEval();
 
 //ExpressionEval();
 //ExpressionEval("5");
@@ -196,6 +197,61 @@ void ExpressionEval(string calc = "9 - (5.5 + 3) * 6 - 4 / ( 9 - 1 )") {
         : scn.ErrorLog.AsConsoleError("Expression Error:"));
 }
 
+// Expression Evaluation - using FexParser
+void TraceExpressionEval(string calc = "9 - (5.5 + 3) * 6 - 4 / ( 9 - 1 )") {
+
+    /*
+     * Expression Grammar:
+     * expression => factor ( ( '-' | '+' ) factor )* ;
+     * factor     => unary ( ( '/' | '*' ) unary )* ;
+     * unary      => ( '-'  unary ) | primary ;
+     * primary    => NUMBER | "(" expression ")" ;
+    */
+
+    // Number Stack for calculations:
+    Stack<double> numStack = new Stack<double>();
+
+    Console.WriteLine($"Calculate: {calc}");
+
+    var fex = new FlowExpression<FexScanner>(new ConsoleTracer());
+
+    var expr = fex.Seq(s => s.Trace(c => "expr:")
+        .Ref("factor")
+        .RepOneOf(0, -1, r => r.Trace(c => "Expr +,-")
+            .Seq(s => s.Ch('+').TraceOp(c => "Check for +", 1).Ref("factor").Act(c => numStack.Push(numStack.Pop() + numStack.Pop())))
+            .Seq(s => s.Ch('-').TraceOp(c => "Check for -", 1).Ref("factor").Act(c => numStack.Push(-numStack.Pop() + numStack.Pop())))
+         ));
+
+    var factor = fex.Seq(s => s.RefName("factor").Trace(c => "factor:")
+        .Ref("unary")
+        .RepOneOf(0, -1, r => r.Trace(c => "Factor *,/")
+            .Seq(s => s.Ch('*').TraceOp(c => "Check for *", 1).Ref("unary").Act(c => numStack.Push(numStack.Pop() * numStack.Pop())))
+            .Seq(s => s.Ch('/').TraceOp(c => "Check for /", 1).Ref("unary")
+                       .Op(c => numStack.Peek() != 0).OnFail("Division by 0") // Trap division by 0
+                       .Act(c => numStack.Push(1 / numStack.Pop() * numStack.Pop())))
+         ));
+
+    var unary = fex.Seq(s => s.RefName("unary").Trace(c => "unary:")
+        .OneOf(o => o
+            .Seq(s => s.Ch('-').TraceOp(c => "  negate unary").Ref("unary").Act(a => numStack.Push(-numStack.Pop())))
+            .Ref("primary")
+         ));
+
+    var primary = fex.Seq(s => s.RefName("primary").Trace(c => "primary:")
+        .OneOf(o => o
+            .Seq(e => e.Ch('(').TraceOp(c => "Primary nesting (", 1).Fex(expr).Ch(')').OnFail(") expected"))
+            .Seq(s => s.NumDecimal(n => numStack.Push(n)).TraceOp((c, v) => $"Primary Number {(double)v}", 1))
+         ).OnFail("Primary expected"));
+
+    var exprEval = fex.Seq(s => s.GlobalPreOp(c => c.SkipSp()).Fex(expr).IsEos().OnFail("invalid expression"));
+
+    var scn = new FexScanner(calc);
+
+    Console.WriteLine(exprEval.Run(scn)
+        ? $"Answer = {numStack.Pop():F4}"
+        : scn.ErrorLog.AsConsoleError("Expression Error:"));
+}
+
 void RefExpressionEval(string calc = "9 - (5.5 + 3) * 6 - 4 / ( 9 - 1 )") 
 {
     /*
@@ -209,7 +265,7 @@ void RefExpressionEval(string calc = "9 - (5.5 + 3) * 6 - 4 / ( 9 - 1 )")
     // Number Stack for calculations:
     Stack<double> numStack = new Stack<double>();
 
-    // The FlowExpression object used to create FexElements with FexScanner as the context:
+    // The FlowExpression factory used to create FexElements with FexScanner as the context:
     var fex = new FlowExpression<FexScanner>();
 
     // Define the main expression production, which returns a Sequence element:
@@ -242,7 +298,7 @@ void RefExpressionEval(string calc = "9 - (5.5 + 3) * 6 - 4 / ( 9 - 1 )")
             .Seq(s => s.Ch('*').Ref("unary").Act(c => numStack.Push(numStack.Pop() * numStack.Pop())))
 
             // If we have a '/' run unary, check for division by zero and then divide the top two values on the stack:
-            // Note again the stack is in reverse order.
+            // o Note again the stack is in reverse order.
             .Seq(s => s.Ch('/').Ref("unary")
                        .Op(c => numStack.Peek() != 0).OnFail("Division by 0") // Trap division by 0 and report as error.
                        .Act(c => numStack.Push(1 / numStack.Pop() * numStack.Pop())))
@@ -293,7 +349,7 @@ void RefExpressionEval(string calc = "9 - (5.5 + 3) * 6 - 4 / ( 9 - 1 )")
     var scn = new FexScanner(calc);
 
     // Run the Axiom with the scanner which returns true/false:
-    // o If valid display the answer = top value on the stack.
+    // o If valid display the answer (= top value on the stack).
     // o Else display the error logged in the scanner's shared ErrorLog.
     Console.WriteLine(exprEval.Run(scn)
         ? $"Answer = {numStack.Pop():F4}"
@@ -373,3 +429,18 @@ public Sample(string name, Action action) {
     }
 }
 
+public class ConsoleTracer : IFexTracer
+{
+    public void Trace(string message, int level) {
+        Console.ForegroundColor = ConsoleColor.Cyan;
+        Console.WriteLine($"{new String(' ', level * 2)}{message}");
+        Console.ForegroundColor = ConsoleColor.White;
+    }
+
+    public void Trace(string message, bool pass, int level) {
+        Console.ForegroundColor = ConsoleColor.Cyan;
+        Console.WriteLine($"{new String(' ', level * 2)}{message} [{pass}]");
+        Console.ForegroundColor = ConsoleColor.White;
+    }
+}
+

FexSampleSet/Program.cs

@@ -7,6 +7,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution
 	ProjectSection(SolutionItems) = preProject
 		LICENSE.txt = LICENSE.txt
 		README.md = README.md
+		Release Backlog.md = Release Backlog.md
 	EndProjectSection
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "FexSampleSet", "FexSampleSet\FexSampleSet.csproj", "{8136AD86-0F27-4A2D-A7E4-9487EE62864D}"
@@ -15,6 +16,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
+		FexGraphs.md = FexGraphs.md
 		Docs\FexOverview.md = Docs\FexOverview.md
 		Docs\FexScannerExt.md = Docs\FexScannerExt.md
 	EndProjectSection

FlowExpressions.sln

@@ -20,6 +20,9 @@ public class FexBuildState<T>
         public FexPreOp<T> PreOp = new FexPreOp<T>(null);  // Will be added to every Op - use for e.g to skip spaces
         public Dictionary<string, FexRef<T>> RefSet = new Dictionary<string, FexRef<T>>();
 
+        public IFexTracer Tracer = null;
+        public bool TraceOn => Tracer != null;
+
         public FexElement<T> Production(FexBuilder<T> builder, FexElement<T> prod, Action<FexBuilder<T>> build) {
             HostFex = prod;
             build?.Invoke(builder);