Skip feature and documentation

Author: promicsw

Docs/FexElementsRef.md

@@ -8,20 +8,24 @@ Flow Expressions are defined by a structure of *FexElements* built via a Fluent
 ## Factory: `FlowExpression<T>`
 
 The `FlowExpression<T>` class operates as a *factory* to build and return FexElements which are used in other productions or as the *Axiom* (root) to be run.
-> The innards of each element are built via the encapsulated `FexBuilder<T>` class.
+> - The innards of each element are built via the encapsulated `FexBuilder<T>` class.
+> - **`Skip()` feature:** Sometimes when parsing spaces/white-space/other needs to be skipped between tokens:
+>    - FexBuilder provides a common Skip() action that can be placed anywhere for this purpose.
+>    - FlowExpression has a method `DefSkip(Action<Ctx> skipAction)` to define what this skip action must be and must be defined before creating any elements.  
 
 **Basic mechanism:**
 ```csharp
 using Psw.FlowExpressions;
 
 // Create a FlowEpression factory using FexScanner as the context:
 var fex = new FlowExpression<FexScanner>();
+    fex.DefSkip(Action<T> skipAction) // Optionally define the Skip action.
 
-// Create a sequence element (element is of type FexElement<T>):
+// Create a sequence element (returned element is of type FexElement<T>):
 var element = fex.Seq(Action<FexBuilder<T>> buildFex);
 
 // Run the element (axiom) with supplied context and process result.
-bool result = element.Run(new FexScanner("text to process"));
+bool result = element.Run(new FexScanner("text to parse"));
 
 // Handle pass or failure:
 ```
@@ -46,6 +50,7 @@ mechanism with methods of the following basic form:
 | [`Op(Func<Ctx, bool> op)`](#id-op) | **Operator:** Perform an operation on the Context returning a boolean result. |
 | [`ValidOp(Action<Ctx> action)`](#id-validop) | **Always valid operator:** Perform and operation on the Context and always returns true. |
 | [`GlobalPreOp(Action<Ctx> preOp)`<br/>`PreOp(Action<T> preOp)`](#id-preop) | **Pre-Operators:** Attach pre-operations to operators. |
+| [`Skip()`<br/>`GlobalSkip()`](#id-skip) | **Skip Action:** Perform a common Skip action previously defined via `FexScanner.DefSkip(...)`. |
 | **Flow Control:** | *These elements control the flow of an expression.* |
 | [`Opt(o => o...)*` ](#id-opt) | **Optional:** Optional sequence. |
 | [`OneOf(o => o...)*`](#id-oneof) | **One Of:** Set of sequences that are *Or'd* together and one of them must succeed to pass. |
@@ -189,6 +194,39 @@ See the Expression example which uses a GlobalPreOp to skip all spaces before th
 
 [`TOC`](#id-toc)
 
+---
+<a id="id-skip"></a>
+### Skip Actions: 
+
+Used when a common skipping action is required between tokens:
+- Typically used to skip spaces, comments and newlines etc. between tokens when parsing scripts. 
+- The action to perform must be pre-defined via `FexExpression.DefSkip(Action<Ctx> skipAction)` and must be defined before any other productions.
+- The Skip operation may be placed anywhere and runs as an action that does not affects the validity of a sequence. If no skip action is define it's just ignored.
+
+<br/>
+
+> **`GlobalSkip()`**  
+> - Sets the skip action as a GlobalPreOp.  
+
+```csharp
+var fex = new FlowExpression<FexScanner>();  // Flow Expression using FexScanner.
+    fex.DefSkip(c => c.SkipSp());            // Define a Skip operation to skip spaces.
+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("3+ digit dialing code expected")
+    .Ch(')').OnFail(") expected")
+    .Skip() // Perform the previously defined skip operation
+    .Rep(3, r => r.Digit(v => acode += v)).OnFail("3 digit area code expected")
+    .AnyCh("- ").OnFail("- or space expected")
+    .Rep(4, r => r.Digit(v => number += v)).OnFail("4 digit number expected")
+ );
+```
+
+[`TOC`](#id-toc)
+
 ---
 <a id="id-opt"></a>
 ### `Optional: Opt(o => o...)`

FexSampleSet/Program.cs

@@ -57,6 +57,7 @@ void RunSamplesFex() {
         new Sample("Simple Scanner 2 (valid)", () => SSDemo.DemoSimpleScanner2(" N3 N1N3-abc")),
         new Sample("Simple Scanner 2 (invalid)", () => SSDemo.DemoSimpleScanner2(" N3 N1N2-ac")),
         new Sample("Expression Eval", () => ExpressionEval()),
+        new Sample("Expression Eval (with tracing)", () => TraceExpressionEval()),
         new Sample("Expression REPL", () => ExpressionREPL()),
     };
 
@@ -96,7 +97,7 @@ void QuickStart() {
      */
 
     var fex = new FlowExpression<FexScanner>();  // Flow Expression using FexScanner.
-        fex.DefSkip(c => c.SkipSp());            // Define the Skip operation to skip spaces.
+        fex.DefSkip(c => c.SkipSp());            // Define a Skip operation to skip spaces.
 
     string dcode = "", acode = "", number = "";  // Will record values in here.
 
@@ -198,7 +199,7 @@ void ExpressionEval(string calc = "9 - (5.5 + 3) * 6 - 4 / ( 9 - 1 )")
         : scn.ErrorLog.AsConsoleError("Expression Error:"));
 }
 
-// Expression Evaluation - using FexParser
+// Expression Evaluation with Tracing example - using FexParser 
 void TraceExpressionEval(string calc = "9 - (5.5 + 3) * 6 - 4 / ( 9 - 1 )") 
 {
     // Expression Grammar:
@@ -426,6 +427,9 @@ public Sample(string name, Action action) {
     }
 }
 
+/// <summary>
+/// IFexTracer implementation for Console output
+/// </summary>
 public class ConsoleTracer : IFexTracer
 {
     public void Trace(string message, int level) {

Psw.FlowExpressions/FexBuilder.cs

@@ -247,11 +247,10 @@ public FexBuilder<T> ActValue<V>(Action<V> valueAction) {
         }
 
         /// <summary>
-        /// Perform the previously defined (via FlowExpression.DefSkip(...)) skip operation:<br/>
-        /// - Typically used to skip spaces etc.<br/>
-        /// - Runs if defined and does no affect the validity of a sequence.
+        /// Perform the previously defined Skip action (define via FlowExpression.DefSkip(...)):<br/>
+        /// - Typically used to skip spaces/white-space etc.<br/>
+        /// - Runs, if defined, as an action and does no affect the validity of a sequence.
         /// </summary>
-        /// <returns></returns>
         public FexBuilder<T> Skip() => Act(_buildState.SkipOp);
 
 
@@ -267,12 +266,12 @@ public FexBuilder<T> GlobalPreOp(Action<T>? preOp) {
         }
 
         /// <summary>
-        /// Binds the previously defined (via FlowExpression.DefSkip(...)) skip operation as pre-operator to all subsequent operators:<br/>
+        /// Binds the previously defined Skip action (define via FlowExpression.DefSkip(...)) as pre-operator to all subsequent operators:<br/>
         /// - A pre-operator executes before an operator as an action on the context:<br/>
-        /// - Typically used to skip spaces etc. before tokens when parsing.<br/>
+        /// - Typically used to skip spaces/white-space etc. before tokens when parsing.<br/>
         /// - Pre-operators are efficient an only execute once while trying several lookahead operations.
         /// </summary>
-        public FexBuilder<T> SkipGlobalPreOp() => GlobalPreOp(_buildState.SkipOp);
+        public FexBuilder<T> GlobalSkip() => GlobalPreOp(_buildState.SkipOp);
 
 
         /// <summary>

Psw.FlowExpressions/Psw.FlowExpressions.csproj

@@ -12,13 +12,14 @@
     <Copyright>2023 Promic Software</Copyright>
     <PackageProjectUrl>https://github.com/promicsw/flow-expressions</PackageProjectUrl>
     <RepositoryUrl>https://github.com/promicsw/flow-expressions</RepositoryUrl>
-    <PackageTags>parser;parser builder;flow logic;c#;</PackageTags>
-    <PackageReleaseNotes>Initial release.</PackageReleaseNotes>
+    <PackageTags>parser;parser-builder;flow-logic;c#;flow-expression;</PackageTags>
+    <PackageReleaseNotes>Skip feature added for common skipping actions during parsing.</PackageReleaseNotes>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <PackageRequireLicenseAcceptance>True</PackageRequireLicenseAcceptance>
     <PackageReadmeFile>Nuget.md</PackageReadmeFile>
     <PackageOutputPath>d:\PromicSW_GitHub\LocalNuget\</PackageOutputPath>
     <PackageIcon>PswLogo.png</PackageIcon>
+    <Version>1.0.1</Version>
   </PropertyGroup>
 
   <ItemGroup>