From fc8773af5b3a550149da80feff44484d6c69a429 Mon Sep 17 00:00:00 2001 From: Theodore Tsirpanis Date: Fri, 20 Mar 2020 13:23:00 +0200 Subject: [PATCH] Write documentation about syntax checking with Farkle. --- docsrc/content/advanced-features.md | 45 +++++++++++++++++++++++++++++ docsrc/content/csharp.md | 8 +++-- docsrc/content/quickstart.fsx | 2 ++ 3 files changed, 53 insertions(+), 2 deletions(-) diff --git a/docsrc/content/advanced-features.md b/docsrc/content/advanced-features.md index f8b1db94..5bb8cf7c 100644 --- a/docsrc/content/advanced-features.md +++ b/docsrc/content/advanced-features.md @@ -129,4 +129,49 @@ RuntimeFarkle AdderRuntime = Adder.BuildUntyped(); `buildUntyped` creates a `RuntimeFarkle` that does not return anything meaningful, and succeeds if the input text is valid. +## Syntax checking + +It is sometimes useful to just check if a string is syntactically valid, instead of giving it a meaning by returning an object out of it. + +This is what the untyped API does, and we can call `buildUntyped` on a typed designtime Farkle to achieve the same. + +Because building a designtime Farkle is expensive, if we already have a runtime Farkle, we can create a new one with the same grammar, but with a post-processor that does nothing. This post-processor is called a _syntax checker_. We can change the post-processor of a runtime Farkle this way: + +__F#:__ +``` fsharp +open Farkle.PostProcessor + +let designtime: DesigntimeFarkle = foo() + +let runtime: RuntimeFarkle = RuntimeFarkle.build designtime + +// syntaxChecker is of type RuntimeFarkle. +let syntaxCheck = RuntimeFarkle.changePostProcessor PostProcessor.syntaxCheck runtime +``` + +__C#:__ +``` csharp +DesigntimeFarkle Designtime = Foo(); + +RuntimeFarkle Runtime = Designtime.Build(); + +RuntimeFarkle SyntaxCheck = Runtime.SyntaxCheck(); +// or +using Farkle.PostProcessor.CSharp; +RuntimeFarkle SyntaxCheck = Runtime.ChangePostProcessor(PostProcessor.SyntaxChecker); +``` + +> The namespaces for the post-processor APIs are a mess and will be streamlined in a next release. + +Changing the post-processor is extremely cheap; no new grammar objects are created, and the syntax-checking post-processor is the same. + +> Actually, the post-processor used in both the F# and the C# example is the same object too. Post-processors are [covariant][covariance] like designtime Farkles, because they are interfaces. Runtime Farkles on the other hand are classes and therefore not variant at all. + +--- + +Farkle has more APIs for various little features that would make this document too lengthy. Fortunately, [they are well-documented in this site](reference.html), as well as while you code. + +So, I hope you enjoyed this little guide. If you did, don't forget to give Farkle a try, and maybe you feel especially untyped today, and want to hit the star button as well. I hope that all of you have a wonderful day, and to see you soon. Goodbye! + [issue-7917]: https://github.com/dotnet/fsharp/issues/7917 +[covariance]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/covariance-contravariance/ diff --git a/docsrc/content/csharp.md b/docsrc/content/csharp.md index 08d9b54d..c96f9bad 100644 --- a/docsrc/content/csharp.md +++ b/docsrc/content/csharp.md @@ -33,11 +33,15 @@ The following table highlights the differences between the F# and C# designtime ### Customizing designtime Farkles -To customize things like the case-sensitivity of designtime Farkles, there are some extension methods for designtime Farkles. +To customize things like the case-sensitivity of designtime Farkles, there are some extension methods for them that reside in the `Farkle` namespace. ## Parsing -To parse text, there are some extension methods for runtime Farkles. +To parse text, there are some extension methods for runtime Farkles that reside in the `Farkle` namespace. + +--- + +So, I hope you enjoyed this little guide. If you did, don't forget to give Farkle a try, and maybe you feel especially sharp today, and want to hit the star button as well. I hope that all of you have a wonderful day, and to see you soon. Goodbye! [fsharp]: quickstart.html [regex]: reference/farkle-builder-regex.html diff --git a/docsrc/content/quickstart.fsx b/docsrc/content/quickstart.fsx index 06cf9a38..4ef42763 100644 --- a/docsrc/content/quickstart.fsx +++ b/docsrc/content/quickstart.fsx @@ -27,6 +27,8 @@ To be able to use a designtime Farkle, we will first feed it to a component call 30: I guess you can't read this line. +> The original idea was to name the designtime Farkles simply _Farkles_, but having a type named `Farkle.Farkle` would create lots of confusion and compile errors. + ## Designing our grammar We want to design a grammar that represents a mathematical expressions on floating-point numbers. The supported operations will be addition, subtraction, multiplication, division, and unary negation. The operator precedence has to be honored, as well as parentheses.