Skip to content

Commit 3e82db6

Browse files
promicswpromicsw
committed
Doc updates
1 parent 4a7f42a commit 3e82db6

File tree

6 files changed

+116
-20
lines changed

6 files changed

+116
-20
lines changed

‎Docs/FexElementsRef.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,7 +64,7 @@ mechanism with methods of the following basic form:
6464
| [`Assert(Func<Ctx, bool> assert, Action<Ctx> failAction)`](#id-assert) | **Assert** if a condition is true else performs failAction. |
6565
| **Inclusion, Forward referencing and Recursion:** | |
6666
| [`Fex(FexElement1, FexElement2, ...)`](#id-fex) | **Include FexElements:** Include a set of previously defined FexElements. |
67-
| [`RefName(string name), Ref(string refName)`](#id-ref) | Forward Referencing and inclusion.|
67+
| [`RefName(string name)`<br>`Ref(string refName)`](#id-ref) | Forward Referencing and inclusion.|
6868
| [`OptSelf()`](#id-optself) | Optional recursive inclusion of the current production sequence within itself. |
6969
| **Tracing:** | *Debugging aid.* |
7070
| [`Trace(Func<Ctx, string> traceMessage, int level = 0)`<br/>`TraceOp(Func<Ctx, string> traceMessage, int level = 0)`<br/>`TraceOp(Func<Ctx, object, string> traceMessage, int level)`](#id-trace) | Tracing utilities. |

‎FexGraphs.md‎ renamed to ‎Docs/FexGraphs.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,26 @@ classDiagram
77
FexElement <|-- Opt
88
FexElement <|-- OneOf
99
FexElement <|-- OptOneOf
10+
FexElement <|-- NotOneOf
1011
FexElement <|-- Rep
1112
FexElement <|-- RepOneOf
13+
FexElement <|-- Op
14+
FexElement <|-- ValidOp
15+
FexElement <|-- PreOp
16+
FexElement <|-- GlobalPreOp
17+
FexElement <|-- Act
18+
FexElement <|-- ActValue
19+
FexElement <|-- RepValue
20+
FexElement <|-- OnFail
21+
FexElement <|-- Fail
22+
FexElement <|-- Assert
23+
FexElement <|-- Fex
24+
FexElement <|-- RefName
25+
FexElement <|-- Ref
26+
FexElement <|-- OptSelf
27+
FexElement <|-- Trace
28+
FexElement <|-- TraceOp
29+
1230
```
1331

1432
### Sequence:

‎FlowExpressions.sln‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,17 +6,17 @@ MinimumVisualStudioVersion = 10.0.40219.1
66
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{C4B8C127-E46C-47AD-BFB4-7054372EC975}"
77
ProjectSection(SolutionItems) = preProject
88
LICENSE.txt = LICENSE.txt
9+
Nuget\Nuget.md = Nuget\Nuget.md
910
README.md = README.md
10-
Release Backlog.md = Release Backlog.md
1111
EndProjectSection
1212
EndProject
1313
Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "FexSampleSet", "FexSampleSet\FexSampleSet.csproj", "{8136AD86-0F27-4A2D-A7E4-9487EE62864D}"
1414
EndProject
1515
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Docs", "Docs", "{16EDBBE2-1A39-49BD-BB7D-1E8B7E9A8BB6}"
1616
ProjectSection(SolutionItems) = preProject
1717
Docs\CustomScanner.md = Docs\CustomScanner.md
18-
FexGraphs.md = FexGraphs.md
1918
Docs\FexElementsRef.md = Docs\FexElementsRef.md
19+
Docs\FexGraphs.md = Docs\FexGraphs.md
2020
Docs\FexOverview.md = Docs\FexOverview.md
2121
Docs\FexScannerExt.md = Docs\FexScannerExt.md
2222
EndProjectSection

‎Nuget/Nuget.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Flow Expressions
2+
3+
4+
Construct, ready to run, Parsers of any complexity using a declarative fluent syntax in C#. The system is lightweight, fast, and loosely coupled components provide complete implementation flexibility.
5+
6+
## Building Flow Expressions
7+
8+
Flow Expressions are defined by a structure of *FexElements* built via a Fluent API. This defines the logical flow and operations of the expression in a very readable format.
9+
10+
Any logic than can be expressed as a Flow Expression (think flow chart) may be implemented.
11+
12+
13+
> A Flow Expression operates on a user supplied **Context**, which is any environment that manages and provides input/content/state.
14+
>
15+
> For a Parser, the context would be a **Scanner** that manages text scanning and provides <i>Tokens</i> to operate on. A comprehensive FexScanner is provided as the default - but you can roll your own if required.
16+
17+
<br>
18+
19+
The following example is a complete **Expression Parser**, including evaluation and error reporting:
20+
21+
```csharp
22+
void ExpressionEval(string calc = "9 - (5.5 + 3) * 6 - 4 / ( 9 - 1 )")
23+
{
24+
// Expression Grammar:
25+
// expr => factor ( ( '-' | '+' ) factor )* ;
26+
// factor => unary ( ( '/' | '*' ) unary )* ;
27+
// unary => ( '-' unary ) | primary ;
28+
// primary => NUMBER | '(' expression ')' ;
29+
30+
// Number Stack for calculations:
31+
Stack<double> numStack = new Stack<double>();
32+
33+
Console.WriteLine($"Calculate: {calc}");
34+
35+
var fex = new FlowExpression<FexScanner>();
36+
37+
var expr = fex.Seq(s => s
38+
.Ref("factor")
39+
.RepOneOf(0, -1, r => r
40+
.Seq(s => s.Ch('+').Ref("factor").Act(c => numStack.Push(numStack.Pop() + numStack.Pop())))
41+
.Seq(s => s.Ch('-').Ref("factor").Act(c => numStack.Push(-numStack.Pop() + numStack.Pop())))
42+
));
43+
44+
var factor = fex.Seq(s => s.RefName("factor")
45+
.Ref("unary")
46+
.RepOneOf(0, -1, r => r
47+
.Seq(s => s.Ch('*').Ref("unary").Act(c => numStack.Push(numStack.Pop() * numStack.Pop())))
48+
.Seq(s => s.Ch('/').Ref("unary")
49+
.Op(c => numStack.Peek() != 0).OnFail("Division by 0") // Trap division by 0
50+
.Act(c => numStack.Push(1 / numStack.Pop() * numStack.Pop())))
51+
));
52+
53+
var unary = fex.Seq(s => s.RefName("unary")
54+
.OneOf(o => o
55+
.Seq(s => s.Ch('-').Ref("unary").Act(a => numStack.Push(-numStack.Pop())))
56+
.Ref("primary")
57+
));
58+
59+
var primary = fex.Seq(s => s.RefName("primary")
60+
.OneOf(o => o
61+
.Seq(e => e.Ch('(').Fex(expr).Ch(')').OnFail(") expected"))
62+
.Seq(s => s.NumDecimal(n => numStack.Push(n)))
63+
).OnFail("Primary expected"));
64+
65+
var exprEval = fex.Seq(s => s.GlobalPreOp(c => c.SkipSp()).Fex(expr).IsEos().OnFail("invalid expression"));
66+
67+
var scn = new FexScanner(calc);
68+
69+
Console.WriteLine(exprEval.Run(scn)
70+
? $"Answer = {numStack.Pop():F4}"
71+
: scn.ErrorLog.AsConsoleError("Expression Error:"));
72+
}
73+
```
74+
75+
<br>
76+
77+
Example **error reporting** for the expression parser above:
78+
79+
```dos
80+
Expression Error:
81+
9 - ( 5.5 ++ 3 ) * 6 - 4 / ( 9 - 1 )
82+
-----------^ (Ln:1 Ch:12)
83+
Parse error: Primary expected
84+
```

‎Psw.FlowExpressions/Psw.FlowExpressions.csproj‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,16 +12,25 @@
1212
<Copyright>2023 Promic Software</Copyright>
1313
<PackageProjectUrl>https://github.com/promicsw/flow-expressions</PackageProjectUrl>
1414
<RepositoryUrl>https://github.com/promicsw/flow-expressions</RepositoryUrl>
15-
<PackageTags>parser;c#;</PackageTags>
16-
<PackageReleaseNotes>Initial release</PackageReleaseNotes>
15+
<PackageTags>parser;flow-logic;c#;</PackageTags>
16+
<PackageReleaseNotes>Initial release.</PackageReleaseNotes>
1717
<PackageLicenseExpression>MIT</PackageLicenseExpression>
1818
<PackageRequireLicenseAcceptance>True</PackageRequireLicenseAcceptance>
19+
<PackageReadmeFile>Nuget.md</PackageReadmeFile>
20+
<PackageOutputPath>d:\PromicSW_GitHub\LocalNuget\</PackageOutputPath>
1921
</PropertyGroup>
2022

2123
<ItemGroup>
2224
<Compile Remove="FexParser.cs" />
2325
</ItemGroup>
2426

27+
<ItemGroup>
28+
<None Include="..\Nuget\Nuget.md">
29+
<Pack>True</Pack>
30+
<PackagePath>\</PackagePath>
31+
</None>
32+
</ItemGroup>
33+
2534
<ItemGroup>
2635
<PackageReference Include="Psw.Scanners" Version="1.0.3" />
2736
</ItemGroup>

‎Release Backlog.md‎

Lines changed: 0 additions & 15 deletions
This file was deleted.

0 commit comments

Comments
 (0)