Skip to content

Match

Name - Description Default Type
<input> The value that's compared with the declared cases. Any
<output> Same value as input if :Passthrough is true else the output of the matched case's shard if :Passthrough is false. Any
Cases Values to match against the input. A nil case will match anything. [] [Any]
Passthrough Parameter to control the shard's output. true allows the Match shard's input itself to appear as its output; false allows the matched shard's output to appear as Match shard's output. true Bool

Compares the input with the declared cases (in order of the declaration) and activates the shard of the first matched case.

Details

Match compares its input with every case declared via the :Cases parameter (in the order of their declaration) till a match is found.

Once a match is found the shard of that matched case is activated/executed and Match execution stops. All subsequent cases (even matching ones) are ignored.

A nil case matches anything, so it's a good practice to declare a nil case at the end of :Cases to execute some default logic if no valid matches exist for a given input. If you do not have a nil case, then a non-matching input to Match will fail the shard.

A note on :Passthrough

The :Passthrough parameter can control the final output of the shard it applies to.

Setting this parameter to true allows the original input of a shard to pass through as its output as well. If this parameter is set to false, passthrough is suppressed and then the output of the shard is the actual computed value coming out from the shard execution.

:Passthrough parameter set to true will allow the original input (the one that was used to match against every case in the shard) to be returned as the final output of Match, irrespective of the case match results. Setting :Passthrough to false will enable the matched case's shard output to be returned as the final output of Match.

However, for :Passthrough to work correctly, the data types of the shard input and the shard's case outputs must match.

Examples

1
2
3
4
5
6
7
8
;; single match + nil match at end + no passthrough
1
(Match [2 (-> "Matched 2")         ;; case processed, match not found
        1 (-> "Matched 1")         ;; case processed, match found
        3 (-> "Matched 3")         ;; case ignored
        nil (-> "Matched nil")]    ;; case ignored 
       :Passthrough false)         ;; no passthrough --
(Assert.Is "Matched 1" true)       ;; -- so matched case's output becomes `Match` shard's output

 

1
2
3
4
5
6
7
8
;; multiple matches + nil match at end + no passthrough
1
(Match [(+ 0 1) (-> "Matched 1a")  ;; case processed, match found
        1 (-> "Matched 1")         ;; case ignored
        2 (-> "Matched 2")         ;; case ignored
        nil (-> "Matched nil")]    ;; case ignored 
       :Passthrough false)         ;; no passthrough --
(Assert.Is "Matched 1a" true)      ;; -- so matched case's output becomes `Match` shard's output

 

1
2
3
4
5
6
7
8
;; multiple matches + nil match at start + with passthrough
1
(Match [nil (-> (Msg "Matched nil"))     ;; case processed, match found
        1 (-> (Msg "Matched 1"))         ;; case ignored
        (+ 0 1) (-> (Msg "Matched 1a"))  ;; case ignored
        2 (-> (Msg "Matched 2"))]        ;; case ignored
       :Passthrough true)                ;; passthrough --
(Assert.Is 1 true)                       ;; -- so input to `Match` is also its output

[info] [shards/General/Match/3.edn] Matched nil

 

1
2
3
4
5
6
7
;; no matches + nil match in the middle + with passthrough
1
(Match [2 (-> (Msg "Matched 2"))         ;; case processed, match not found
        nil (-> (Msg "Matched nil"))     ;; case processed, match found
        3 (-> (Msg "Matched 3"))]        ;; case ignored
       :Passthrough true)                ;; passthrough --
(Assert.Is 1 true)                       ;; -- so input to `Match` is also its output

[info] [shards/General/Match/4.edn] Matched nil