Skip to content

PatternMatchingUnions

Jump to bottom Edit New page
David Arno edited this page Nov 4, 2015 · 9 revisions

Pattern Matching

Succinc<T> pattern matching guide: Unions

Introduction

This pattern matching guide is split into the following sections:

A union can contain precisely one of a set of different data types. Pattern matching on unions therefore consists of matching value of those various types, via Case1() through Case4().

Syntax

The generalised syntax for option patterns can be expressed using BNF-like syntax. As with all Succinc<T> pattern matching cases, there are two types of match. Firstly, matching and returning a value:

result = {union}.Match<{result type}>()
                [CaseExpression]...
                [ElseExpression]
                .Result();

CaseExpression ==>
    .CaseN().Do({value} => {result type expression}) |
    .CaseN().Do({result type expression}) |
    .CaseN() [WithExpression|WhereExpression]...

WithExpression ==> 
    .With({value})[.Or({value})]... .Do({value} => {result type expression}) |
    .With({value})[.Or({value})]... .Do({result type expression})

WhereExpression ==>
    .Where({item} => {boolean expression}).Do({value} => {result type expression}) |
    .Where({item} => {boolean expression}).Do({result type expression})

ElseExpression ==>
    .Else({option} => {result type expression}) |
    .Else({result type expression})

CaseN ==> Case1|Case2|Case3|Case4

And the alternative is a match that invokes a void expression (ie, an Action<{item type}>):

{union}.Match()
        [CaseExpression]...
        [ElseExpression]
        .Exec();

CaseExpression ==>
    .CaseN().Do({value} => {action on value}) |
    .CaseN() [WithExpression|WhereExpression]...

WithExpression ==> 
    .With({value})[.Or({value})]... .Do({value} => {action on value})

WhereExpression ==>
    .Where({item} => {boolean expression}).Do({value} => {action on value})

ElseExpression ==>
    .Else({option} => {action on option}) |
    .IgnoreElse()

CaseN ==> Case1|Case2|Case3|Case4

To explain the above syntax:

  • {} denotes a non-literal, eg {void expression} could be the empty expression, {}, or something like Console.WriteLine("hello").
  • Items in [] are optional.
  • | is or, ie [x|y] reads as "an optional x or y".
  • ... after [x] means 0 or more occurrences of x.
  • ==> is a sub-rule, which defines the expression on the left of this symbol.

Important note Case4 is only supported when matching on Union<T1,T2,T3,T4>. Case3 is only supported when matching on Union<T1,T2,T3> and Union<T1,T2,T3,T4>.

Basic Usage

The most basic form is matching on which type a union contains:

public static bool ContainsRectangle(Union<Rectangle, Circle> shape)
{
    return shape.Match<bool>()
                .Case1().Do(x => true)
                .Case2().Do(x => false)
                .Result();
}

public static void PrintShape(Union<Rectangle, Circle> shape)
{
    shape.Match()
         .Case1().Do(Console.WriteLine("Rectangle"))
         .Case2().Do(Console.WriteLine("Circle"))
         .Exec();
}

In ContainsRectangle, we test against Case1() (rectangle) and Case2() (circle) to return true/false accordingly. In PrintShape, we test against Case1() and Case2() once more, and invoke an action to print the shape type that corresponds to the union's state.

In both cases, we have used both Case1() and Case2(), but we could optionally use Else():

public static bool ContainsRectangle(Union<Rectangle, Circle> shape)
{
    return shape.Match<bool>()
                .Case1().Do(x => true)
                .Else(x => false)
                .Result();
}

public static void PrintShape(Union<Rectangle, Circle> shape)
{
    shape.Match()
         .Case2().Do(Console.WriteLine("Circle"))
         .Else(Console.WriteLine("Rectangle"))
         .Exec();
}

Else() or IgnoreElse() is invoked if there is no match from any specified Case1() or Case2() expressions respectively.

One further change can be made to the functional example. We are supplying a parameter, x, which isn't then used. In this case, we can dispense with the lambda and just specify the return value:

public static bool ContainsRectangle(Union<Rectangle, Circle> shape)
{
    return shape.Match<bool>()
                .Case1().Do(true)
                .Else(false)
                .Result();
}

Matching Individual Values

The previous examples just matched each case of the union with any value. We might want to match specific values though. We can use this feature as part of a simple calculator:

public static ExpressionNode CreateExpressionNode(Union<string, float> token)
{
    return token.Match<ExpressionNode>()
                .Case1("+").Do(new ExpressionNode(x, y => x + y))
                .Case1("-").Do(new ExpressionNode(x, y => x - y))
                .Case1("/").Do(new ExpressionNode(x, y => x / y))
                .Case1("*").Do(new ExpressionNode(x, y => x * y))
                .Else(x => new ExpressionNode(x))
                .Result();
}

CreateExpressionNode will create an instance of some type, ExpressionNode, that takes either a Func<float, float, float> or float parameter. For the former, it constructs a lambda function to perform the appropriate calculation. For the latter, it just stores the number supplied.

It's often the case that more than one value needs to match a particular pattern. We have two choices here: we can use Or() or Where().

Firstly, using Or we could write a more advanced CreateExpressionNode method:

public static ExpressionNode CreateExpressionNode(Union<string, float> token)
{
    return token.Match<ExpressionNode>()
                .Case1("+").Or("-".Or("*").Or("/").Do(x  => ArithmaticExpression)
                .Case1("(").Do(new ExpressionNode(SpecialAction.StartGroup)
                .Case1(")").Do(new ExpressionNode(SpecialAction.EndGroup)
                .Else(x => new ExpressionNode(x))
                .Result();
}

Here we now match +, -, / and * together and invoke a method ArithmaticExpression that returns one of the four previously described lambdas. ExpressionNode now accepts an enum SpecialAction too, which is used to denote the start and end of a grouping (via ()).

If we want to check a range of values, we can use Where:

public static void PositiveOrNegative(Union<string, int> token)
{
    data.Match()
        .Case2().Where(i => i < 0).Do(_ => Console.WriteLine("Negative"))
        .Case2().Where(i => i > 0).Do(_ => Console.WriteLine("Positive"))
        .Case2().Do(_ => Console.WriteLine("Zero"))
        .Else("Not a number")
        .Exec();
}

Match Order

So far, we have only considered distinct match patterns, ie where there is no overlap. In many cases, more than one Case1() or Case2() pattern will be required and the match patterns may overlap. The following function highlights this:

public static string OddOrNegative(Union<string, int> token)
{
    return data.Match<string>()
               .Case2().Where(i => i % 2 == 1).Do(_ => Console.WriteLine("Odd"))
               .Case2().Where(i => i < 0).Do(_ => Console.WriteLine("Negative"))
               .Else("Neither")
               .Result();
}

Clearly in this situation, all negative odd integers will match both Where clauses. The matching mechanism tries each match in the order specified and stops on the first match. So OddOrPositive(new Union<string, int>(1)) will return Odd, rather than Negative.

Add a custom footer

Contents

Clone this wiki locally