Migration Guide

This article describes how to migrate to version 2.0.0 from PatternMatching v1.2.0.

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.

In order to migrate from version 2.0.0 to version 2.1.0 action is required only if you implemented the IPattern<TInput, TMatchResult> interface (which wasn't recommended). The less generic IPattern<TInput> interface was removed, so you should remove its Match method. That's it.

To migrate from version 2.1.0 to 3.0.0, you need a platform which supports .NET Standard 2.1. If it does, then you can upgrade without any fuss as this version doesn't contain breaking changes.

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 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 must 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. Bear in mind that IPattern<TInput> was removed in version 2.1.0 so don't bother with it much.

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