Finish updating the documentation

Author: TolikPylypchuk

CHANGELOG.md

@@ -9,20 +9,21 @@ What's new in version 2.0 (almost all changes are breaking):
 - Dropped the dependency on [language-ext](https://github.com/louthy/language-ext)
 - Completely updated the pattern hierarchy and built-in patterns
 - The deprecated `StructNull` pattern is removed
-- Matching with fallthrough became lazy
-- Strict matching with fallthrough was removed
+- Matching with fall-through became lazy
+- Strict matching with fall-through was removed
 - Descriptions were added to patterns
-- Creating custom patterns became possible through factory methods
-and extension methods
+- Creating custom patterns became possible through factory methods and extension methods
 - The default mode of match statements changed from non-strict to strict
 
+Read the [migration guide](https://tolikpylypchuk.github.io/Matchmaker/v2.0.0/articles/migration.html) for more info.
+
 ## v1.2
 
 What's new in version 1.2:
 
 - Added tests
 - Deprecated the `StructNull` pattern in favour of `ValueNull`
-- Fixed a bug which made strict matching with fallthrough unusable
+- Fixed a bug which made strict matching with fall-through unusable
 - Fixed null handling in some predefined patterns
 - Minor code refactoring
 
@@ -33,7 +34,7 @@ What's new in version 1.1:
 - `Matcher` classes renamed to `Match` (breaking change).
 - `OptionUnsafe` is now used instead of `Option` in patterns to fully support `null` values (breaking change).
 - `ExecuteOnStrict` in `Match<TInput>` renamed to `ExecuteStrict` (breaking change).
-- Implemented matching with fallthrough
+- Implemented matching with fall-through
 - Added two new patterns - `Null` for classes and `StructNull` for nullable structs.
 
 Although there are several breaking changes, the major version is not incremented, as these changes

Matchmaker/MatchException.cs

@@ -22,7 +22,8 @@ public MatchException()
         /// Initializes a new instance of the <see cref="MatchException" /> class.
         /// </summary>
         /// <param name="message">The message which describes this exception.</param>
-        public MatchException(string message) : base(message)
+        public MatchException(string message)
+            : base(message)
         { }
 
         /// <summary>

README.md

@@ -1,20 +1,21 @@
 # Matchmaker
 
+[![NuGet](https://img.shields.io/nuget/v/Matchmaker.svg)](https://www.nuget.org/packages/Matchmaker/)
 [![Build status](https://ci.appveyor.com/api/projects/status/wptuo5d5mi4blss0?svg=true)](https://ci.appveyor.com/project/TolikPylypchuk/matchmaker)
 
-A library which enables more powerful pattern matching
-than is currently available in the C#'s `switch` statement/expression.
+A library which enables more powerful pattern matching than is currently available in the C#'s `switch`
+statement/expression.
 
-This library is a successor of
-[PatternMatching](https://github.com/TolikPylypchuk/PatternMatching).
+This library is a successor of [PatternMatching](https://github.com/TolikPylypchuk/PatternMatching).
 Version 1.x can be found there. This repository contains version 2+.
 
 ## Installation
 
-This library cannot be installed through NuGet until version 2.0 is released.
-For now you can install the [older version](https://www.nuget.org/packages/CSharpStuff.PatternMatching/).
+```
+Install-Package Matchmaker -Version 2.0.0
+```
 
-## A simple example
+## A Simple Example
 
 This is what the simplest match expression looks like:
 
@@ -61,33 +62,59 @@ switch (i)
 }
 ```
 
-While this example doesn't show the full power of pattern matching, there are
-a few things to note here:
+While this example doesn't show the full power of pattern matching, there are a few things to note here:
 
- - The match expression yields a result. We don't have to assign the result
-explicitly in each case.
+ - The match expression yields a result. We don't have to assign the result explicitly in each case.
 
- - The input of the match expression is specified _after_ all the cases. This
-allows us to save the match expression in an object, and use it multiple times
-on different input values.
+ - The input of the match expression is specified _after_ all the cases. This allows us to save the match expression
+in an object, and use it multiple times on different input values.
 
- - The default case is a pattern, just like any other. It's called `Any` and
-is always matched successfully.
+ - The default case is a pattern, just like any other. It's called `Any` and is always matched successfully.
 
- - Like in `switch` the patterns are tried out sequentially. This means that
-the `Any` pattern should always come last.
+ - Like in `switch` the patterns are tried out sequentially. This means that the `Any` pattern should always
+come last.
 
-The release C# 8.0 included a new way to write switch expressions which yield a value.
-While this drastically reduced the need for external libraries like this one
-for pattern matching, the language itself includes only the simplest patterns.
-This library lets the user define arbitrary patterns, which makes this library
-more powerful than the switch expressions.
+The release C# 8.0 included a new way to write `switch` expressions which yield a value. While this drastically reduced
+the need for external libraries like this one for pattern matching, the language itself includes only the simplest
+patterns. This library lets the user define arbitrary patterns, which makes this library more powerful than the
+`switch` expressions.
+
+Here's what the equivalent switch expression looks like in C# 8.0:
+
+```
+int i = 5;
+
+string result = i switch
+{
+    1 => "one",
+    2 => "two",
+    3 => "three",
+    4 => "four",
+    _ => i.ToString()
+};
+```
+
+OK, this is much shorter and cleaner than the previous two examples. But this library shines when the patterns are
+more complex. C# allows only constant patterns, type patterns, and `when` expressions. This library allows anything
+you can think about.
 
 ## More Info
 
+If you want to learn how to use this library, you should read the
+[documentation](https://tolikpylypchuk.github.io/Matchmaker/v2.0.0). The articles provide everything you need to know
+to use this library.
+
+If you need extensive information, go to the
+[API reference](https://tolikpylypchuk.github.io/Matchmaker/v2.0.0/api/index.html).
+
+If you need even more info about this library, you can go through the
+[tests](https://github.com/TolikPylypchuk/Matchmaker/tree/v2.0.0/Matchmaker.Tests). They are property-based and as such
+they describe every aspect of the classes and their members.
+
 The documentation can be found here:
 
  - Version 2.0.0: https://tolikpylypchuk.github.io/Matchmaker/v2.0.0
+ - Older versions: https://github.com/TolikPylypchuk/PatternMatching
 
 ## License
 

docs/articles/expressions.md

@@ -1,4 +1,4 @@
-## Match Expressions
+# Match Expressions
 
 The second central idea is the match expression itself. It is represented by two classes: `Match<TInput, TOutput>`
 and `Match<TInput>`. The difference between them is that the former represents a match expression which yields
@@ -13,7 +13,7 @@ A match expression can be created using the `Create` methods of the static class
 ### Adding Cases
 
 The `Match` classes include `Case` methods which are used to add a pattern and a function which is executed if
-the match is successful. Match expressions are immutable - `Case` methods return new match expressions, they
+the match is successful. Match expressions are immutable - `Case` methods return new match expressions; they
 do not affect the ones on which they are called.
 
 `Case` methods are generic - they also contain information about the pattern's transformation type. Match expressions
@@ -24,23 +24,24 @@ expressions.
 ### Executing Match Expressions
 
 To execute a match expression, the `ExecuteOn` method is used. It takes the input value to match. There are two modes
-of execution in match expressions: strict and non-strict. The strict mode throws an exception and the non-strict doesn't.
+of execution in match expressions: strict and non-strict. The strict mode throws an exception if no matches were found,
+and the non-strict doesn't.
 
-In the `Match<TInput, TOutput>` class the `ExecuteOn` method returns the result of the match, or throws a
+In the `Match<TInput, TOutput>` class the `ExecuteOn` method returns the result of the match or throws a
 `MatchException` if no successful match was found. `Match<TInput, TOutput>` also contains the `ExecuteNonStrict`
-method which executes the match expression in the non-strict mode. It returns `MatchResult<TOutput>`, because
+method which executes the match expression in the non-strict mode. It returns `MatchResult<TOutput>` because
 the result might not be present.
 
-In the `Match<TInput>` class the `ExecuteOn` method doesn't return anyhting, and also throws the `MatchException`
+In the `Match<TInput>` class the `ExecuteOn` method doesn't return anything, and also throws a `MatchException`
 if the match wasn't successful. This class also contains the `ExecuteNonStrict` method - it returns a boolean value
-which indicates whether the match was successful, and doesn't throw an exception if it wasn't.
+which indicates whether the match was successful and doesn't throw an exception if it wasn't.
 
 The `ToFunction` method and its variations are also available. They return a function which, when called, will execute
 the match expression.
 
 ## Matching with Fall-through
 
-C, C++ and Java support fall-through in `switch` expressions. So does this library, although it works differently here.
+C, C++ and, Java support fall-through in `switch` statements. So does this library, although it works differently here.
 
 Fall-through must be explicitly enabled for cases and then explicitly enabled during execution. Both `Match` classes
 contain the `ExecuteWithFallthrough` method which takes fall-through behavior into account. `ExecuteOn` and
@@ -49,16 +50,16 @@ contain the `ExecuteWithFallthrough` method which takes fall-through behavior in
 If a case has fall-through enabled, then the expression falls to the _next successful_ match, unlike `switch`, which
 falls to the next case whether it's successful or not.
 
-Matching with fall-through is lazy i.e. it returns an `IEnumerable` and is only executed when this enumerable
-is enumerated. Because matching will fall-through is lazy, it doesn't have any modes of execution - the user must
-decide whether to throw exceptions or not if there were no successful matches.
-
 The `Case` methods are overloaded to accept a boolean value which indicates the fall-through behavior. If fall-through
 is enabled for a pattern, then the expression will continue searching for the next successful pattern. If it isn't, then
 the expression will stop at this pattern and not go any further.
 
 `Match.Create` is also overloaded to take the default fall-through behavior.
 
+Matching with fall-through is lazy i.e. it returns an `IEnumerable` and is only executed when this enumerable
+is enumerated. Because matching will fall-through is lazy, it doesn't have any modes of execution - the user must
+decide whether to throw an exception or not if there were no successful matches.
+
 In the `Match<TInput, TOutput>` class the `ExecuteWithFallthrough` method returns an `IEnumerable<TOutput>`
 which can be used to get all successful match results.
 
@@ -76,7 +77,7 @@ it and ignores the result. You can use it if you just want to execute the match
 
 **Remember: matching with fall-through is lazy and is actually executed when the result is enumerated.**
 
-Here's a (somewhat convulted) implementation of the famous fizz-buzz program which uses matching with fall-through:
+Here's a (somewhat convoluted) implementation of the famous fizz-buzz program which uses matching with fall-through:
 
 ```
 using System.Linq;
@@ -107,8 +108,8 @@ var result = Enumerable.Range(0, 15)
 
 ### The Initialization Problem
 
-One pain point of match expressions is that wherever a method which contains a match expression is executed, the match
-expression is initialized from scratch. Take a look at the example:
+One pain point of match expressions is that whenever a method which contains a match expression is executed, the match
+expression is initialized from scratch. Take a look at this example:
 
 ```
 void DoStuff(int i)
@@ -125,14 +126,14 @@ as well, even though it's actually the same expression. Having just 4 cases may
 accumulate if we execute it thousands of times.
 
 We can save the expression in a field and then call the `ExecuteOn` method on this field. But this makes the code
-much less readable, because the case definitions are in a different place from the actual execution point.
+much less readable because the case definitions are in a different place from the actual execution point.
 
 ### The Solution
 
 There is a way to create 'static match expressions' - expressions which will be initialized only once.
 
-The `Match` class contains `CreateStatic` methods which allow the creation of static match expressions. Take a look
-at the modified example.
+The `Match` class contains the `CreateStatic` methods which allow the creation of static match expressions.
+Take a look at the modified example:
 
 ```
 void DoStuff(int i)
@@ -144,9 +145,9 @@ void DoStuff(int i)
         .ExecuteOn(i);
 ```
 
-It looks almost the same, except for one difference: he calls to `Case` methods are inside the lambda expression,
-called the build action, which is passed to the `CreateStatic` method. Now this match expressions will be initialized
-only once and its initialization code is in the same place as its execution point.
+It looks almost the same, except for one difference: the calls to `Case` methods are inside the lambda expression,
+called the build action, which is passed to the `CreateStatic` method. Now this match expression will be initialized
+only once, and its initialization code is in the same place as its execution point.
 
 The parameter of the build action has the type `MatchBuilder<TInput, TOutput` or `MatchBuilder<TInput>`
 depending on which type of match expressions you are building. This type has the same methods for adding cases as

docs/articles/intro.md

@@ -82,15 +82,24 @@ you can think about.
 
 ## Performance
 
-Versions 1.x used the DLR to provide type-safe pattern matching on any types
-without having to remember all those types. Thus the performance was _much_
-worse than C#'s switch statements/expressions (even though I didn't perform
-any benchmarks).
-
-Versions 2+ of this library don't use the DLR anymore - I've found a better way
-to do this, and frankly, I'm amazed I didn't think of this way before. So I'm
-guessing the performance of the new versions must be much better than versions 1.x.
-Maybe, I'll even implement some benchmarks in the future to compare the performance
-of this library in comparison to the switch statements/expressions.
+Versions 1.x used the DLR to provide type-safe pattern matching on any types without having to remember all those types.
+Thus, the performance was _much_ worse than C#'s switch statements/expressions (even though I didn't perform any
+benchmarks).
+
+Versions 2+ of this library don't use the DLR anymore - I've found a better way to do this, and frankly, I'm amazed I
+didn't think of this way before. So, I'm guessing the performance of the new versions must be much better than versions
+1.x.
+
+## More Info
+
+If you want to learn how to use this library, you should read these articles. They provide everything you need to know
+to use this library.
+
+If you need extensive information, go to the [API reference](../api/index.md).
+
+If you need even more info about this library, you can go through the
+[tests](https://github.com/TolikPylypchuk/Matchmaker/tree/v2.0.0/Matchmaker.Tests). They are property-based and as such
+they describe every aspect of the classes and their members. They cover 100% of this library's code (except
+the `MatchException` class which is trivial).
 
 Next article: [Match results](results.md).

docs/articles/migration.md

@@ -1,3 +1,63 @@
 # Migration Guide
 
+This article describes how to migrate to version 2.0.0 from
+[PatternMatching v1.2.0](https://github.com/TolikPylypchuk/PatternMatching).
+
+If you need to migrate from older versions, first migrate to version 1.2.0. You can do that just by reading the
+changelog, because previous versions contained much fewer changes and it's much simpler to migrate.
+
+## General
+
+Since this library has a new name, the namespace is different as well. Instead of the `PatternMatching` namespace
+there are three namespaces: `Matchmaker`, `Matchmaker.Patterns` and `Matchmaker.Linq`.
+
+The dependency on [language-ext](https://github.com/louthy/language-ext) was dropped. Instead of using `OptionUnsafe`
+this library now uses its own `MatchResult`.
+
+## Patterns
+
+The predefined patterns haven't changed much, but the way to create custom patterns changed drastically.
+
+The `Match` method in `IPattern<TInput, TMatchResult>` now returns `MatchResult<TMatchResult>` instead of
+`OptionUnsafe<TMatchResult>`.
+
+The `IPattern<TInput, TMatchResult>` now contains the `Description` property. If you implemented this interface,
+you can add it and make it return an empty string if you don't want a description.
+
+`IPattern<TInput, TMatchResult>` now extends `IPattern<TInput>`. If you implemented this interface, it's better
+to extend the new `Pattern<TInput, TMatchResult>` class instead, as it provides both an implementation of the less
+generic interface, and the `Description` property.
+
+The `ConditionalPattern<TInput, TMatchResult, TPattern>` is gone. It's too much work for the users to implement
+filtering of patterns if they want a highly customized pattern. If you filtered pattern results with the `When` method
+before, now  you can do that using the `Where` extension method from the `Matchmaker.Linq` namespace, which works on
+all patterns, and doesn't need a special base class. I renamed this method because previously I wanted it to look like
+the `when` clause of the `switch` expressions, but now this method is part of LINQ to Patterns, so `Where` is more
+appropriate.
+
+`SimplePattern<TInput>` is gone and `Pattern<TInput, TMatchResult>` now serves as a base class for patterns.
+If you need to create a pattern from a function or a predicate, use the `CreatePattern` methods in the `Pattern`
+class.
+
+Since `SimplePattern<TInput>` is gone, you cannot use operators to compose patterns (`&`, `|` and `^`). Also,
+the `And`, `Or` and `Xor` methods are not part of pattern definition - they are extension methods from the
+`Matchmaker.Linq` namespace. The `~` operator is gone as well. Use `Not` instead.
+
+The `StructNull` pattern is gone. It was deprecated in version 1.2.0. The `ValueNull` pattern provides the same
+functionality.
+
+## Match Expressions
+
+The default mode of execution for match statements is now strict. So `ExecuteOn` is strict. The `ExecuteStrict`
+method is gone and `ExecuteNonStrict` is added. This was changed because it was weird to have different default modes
+in match expressions and match statements.
+
+Matching with fall-through became lazy. This is major change. The result in match expressions is now not the `Lst`
+from language-ext, but a lazy `IEnumerable` which the user has to enumerate for the match to actually be executed.
+Match statements also return an `IEnumerable` instead of a number of successful cases. If you want to know the number
+of successful cases, you can call `Count()` on the result of the match. Or you can call `Enumerate` from
+`Matchmaker.Linq` if you just want to execute it. Since matching with fall-though is lazy, it doesn't have modes
+of execution - it's just non-strict. The library cannot decide to throw an exception if there are no successful cases
+because the library doesn't decide when to execute the expression.
+
 Next article: [Why this library was written](why.md)