Add more cases to pattern matching

codingedgar commented 2 years ago

Hi 👋 !

Thank you all for this documentation, it is superb a huge help learning the language!

I have a bit of trouble demystifying pattern matching in PureScript coming from F#, I want to present some improvements to the docs along with my time to make it happen 🐬

F# patterns documentation has an outstanding display of what is possible with Pattern Matching.

Is it possible to express all F# patterns with PureScript patterns? I assume they are with PureScript current patterns or Guard Patterns (except for Type Test Pattern which test types at runtime).

Can examples like F#'s OR Pattern and AND Pattern be exemplified?

OR Pattern

// F#
let detectZeroOR point =
    match point with
    | (0, 0) | (0, _) | (_, 0) -> printfn "Zero found."
    | _ -> printfn "Both nonzero."
detectZeroOR (0, 0)
detectZeroOR (1, 0)
detectZeroOR (0, 10)
detectZeroOR (10, 15)

-- PureScript
detectZeroOR :: Tuple Int Int -> String
detectZeroOR point
    | (Tuple 0 0) <- point
    , (Tuple 0 _) <- point
    , (Tuple _ 0) <- point =  "Zero found."
    | otherwise = "Both nonzero."

I'm not sure if this is the best way to express the OR Pattern in PureScript, as I repeat <- point many times.

Maybe this is not the best example for the OR Pattern as I could check the fst and snd values in the guard. Still, the OR Pattern point is that all subpatterns have all the capabilities of a match expression; I can nest and apply other patterns, but that's just what is in the F# docs, and it's legible.

Multiple values pattern

The pattern to match multiple values is not exemplified (also not sure if nicer Tuple syntax or an actual pattern):

case path, role of
  "/admin", Admin -> Allow
  "/admin", _ -> Deny
  _, _ -> Allow

According to https://github.com/purescript/purescript/issues/1687 and https://github.com/purescript/purescript/pull/1696, it seems like it is not related to tuples at all. In F#, there's a Tuple Pattern which provides a nicer syntax to pattern match multiple values, but it seems that it is its own thing in PureScript, not related to tuples which seem to be covered by PS Constructor patterns.

Match Expression and Pattern Matching Function

For the OR Pattern example, the only way I knew how to make it work was by following Pattern Guards docs in something like an F# Pattern matching function, which has no name for it in the PureScript docs, it would be nice to have an explicit way to call it in PureScript as well, I assume there is, just not documented.

In F# for example the names are Match expression and Pattern matching function:

// Match expression.
match test-expression with
| pattern1 [ when condition ] -> result-expression1
| pattern2 [ when condition ] -> result-expression2
| ...

// Pattern matching function.
function
| pattern1 [ when condition ] -> result-expression1
| pattern2 [ when condition ] -> result-expression2
| ...

Which by the way is expressed in a very clear syntax, currently the PS docs miss the guards and the distinctive use of -> in match expressions vs = in match expressions with guards:

https://github.com/purescript/documentation/blob/7295b335dfbda17015e68f4c74b81e91007f79b8/language/Pattern-Matching.md#L7-L12

Minor pick

In https://github.com/purescript/documentation/blob/7295b335dfbda17015e68f4c74b81e91007f79b8/language/Pattern-Matching.md#L14

I can see the Lang Guide used to be just one file, but now that it is multiple files, as we have already seen is confusing for newcomers as I'm reading that file straight from a Google search, I assume to be read independently from the rest of the language guide.

rhendric commented 2 years ago

There's some good feedback here; thanks!

As you've noted, the division of the language guide into multiple files is a little ad-hoc, and some things are difficult to discover if you aren't reading the entire thing. Several of the syntaxes you're asking about are in the Case expressions section of Syntax.md, instead of in Pattern-Matching.md.

PureScript doesn't have an equivalent to F#'s OR patterns; it was discussed in https://github.com/purescript/purescript/issues/542 back in PureScript's infancy, but nothing came of it. Multiple pattern guards separated by commas all must match for that branch to be selected, so the example you gave in PureScript is actually analogous to an F# AND pattern.

codingedgar commented 2 years ago

@rhendric Thanks a lot for replying!

Thank you for pointing out the syntax section, I guess it could be ok to duplicate that in the pattern matching section.

so the example you gave in PureScript is actually analogous to an F# AND pattern. Thanks! Good to know that's an AND Pattern and OR is not expressable rn 👍

purescript / documentation