ginger/doc/pattern.md

Pattern Matching

Pattern matching in ginger is used both to assign variables and test for the contents of them.

Assignment

The = function's job is to assign values to variables. In the simplest case:

(= Foo 5)

Assigns the value 5 to the variable named Foo. We can assign more complicated values to variables as well:

(= Foo [1 2 3 4])

Deconstruction

With pattern matching, we can deconstruct the value on the right side and assign its individual parts to their own individual variables:

[
    (= [Foo Bar [Baz Box] Bus] [1 a [3 4] [5 6]])
    (println Foo)
    (println Bar)
    (println Baz)
    (println Box)
    (println Bus)
]

The above would print out:

1
a
3
4
[5 6]

No Match

What happens if we try to pattern match a value that doesn't match the left side?:

(= [Foo Bar Baz Box] [1 2 3]) ; => [error nomatch]

The value itself is a vector with three items, but we want a vector with four! This returns an error and none of the variables were assigned.

Blanks

If there's a variable we expect the right side to have, but we don't actually want to do anything with it, we can use _:

(= [Foo _ Baz] [1 2 3])

The above would assign 1 to Foo and 2 to Baz.

Left-side checks

The left side isn't exclusively used for assignment, it can also be used to check certain values on the right:

(= [1 Foo 2 Bar] [1 a 2 b]) ; => success
(= [1 Foo 2 Bar] [1 a 3 b]) ; => [error nomatch]

If a variable is already defined it can be used as a check as well:

[
    (= Foo 1)
    (= [Foo Foo Bar] [1 1 2]) ; => success
    (= [Foo Foo Baz] [1 2 3]) ; => [error nomatch]
]

Finally, undefined variables on the left side that are used more than once are ensured that all instances have the same value:

[
    (= [Foo Foo Foo] [foo foo foo]) ; => success
    (= [Bar Bar Bar] [foo bar bar]) ; => [error nomatch]
]

Vectors

What if we don't know the full length of the vector, but we only want to retrieve the first two values from it?:

(= [Foo Bar -] [1 2 3 4 5])

The above would assign 1 to Foo and 2 to Bar. - is treated to mean "zero or more items in the sequence that we don't care about".

What if you want to match on the tail end of the vector?:

(= [- Bar Foo] [1 2 3 4 5])

The above would assign 4 to Bar and 5 to Foo.

Can we do both?:

(= [Foo - Bar] [1 2 3 4 5])

The above would assign 1 to Foo and 5 to Bar.

Lists

Everything that applies to vectors applies to lists, as far as pattern matching goes:

(= (Foo Bar Baz -) (l (foo bar baz)))

In the above foo is assigned to Foo, bar to Bar, and baz to Baz.

Note that the right side needs the l literal wrapper to prevent evaluation, while the left side does not. Nothing on the left will ever be evaluated, if you want it to be dynamically defined you'll have to use a macro.

Maps

Pattern matching can be performed on maps as well:

(= { Foo Bar } { a b }) ; => success
(= { Foo Bar } { a b c d }) ; => [error nomatch]
(= { Foo Bar - - } { a b c d }) ; => success

In the last case, the important thing is that the key is -. This tells the matcher that you don't care about any other keys that may or may not exist. The value can be anything, but - seems semantically more correct imo.