Alternative extractor implementation

Project.toml

@@ -1,6 +1,6 @@
 name = "Match"
 uuid = "7eb4fadd-790c-5f42-8a69-bfa0b872bfbf"
-version = "2.2.0"
+version = "2.3.0"
 authors = ["Neal Gafter <[email protected]>", "Kevin Squire <[email protected]>"]
 
 [deps]

README.md

@@ -48,7 +48,7 @@ for examples of this and other features.
 * `T(y=1)` matches structs of type `T` whose `y` field equals `1`
 * `[x,y,z]` matches `AbstractArray`s with 3 entries matching `x,y,z`
 * `(x,y,z)` matches `Tuple`s with 3 entries matching `x,y,z`
-* `[x,y...,z]` matches `AbstractArray`s with at least 2 entries, where `x` matches the first entry, `z` matches the last entry and `y` matches the remaining entries.
+* `[x,y...,z]` matches `AbstractArray`s with at least 2 entries, where `x` matches the first entry, `z` matches the last entry and `y` matches the remaining entries
 * `(x,y...,z)` matches `Tuple`s with at least 2 entries, where `x` matches the first entry, `z` matches the last entry and `y` matches the remaining entries.
 * `::T` matches any subtype (`isa`) of type `T`
 * `x::T` matches any subtype (`isa`) of T that also matches pattern `x`
@@ -89,6 +89,53 @@ When `pattern1` matches but `some_failure_condition` is `true`, then the whole c
 Otherwise, if `some_shortcut_condition` is `true`, then `1` is the result value for this case.
 Otherwise `2` is the result.
 
+## Extractors
+
+Struct patterns of the form `T(x1,...,xn)` can be overridden by defining an _extractor_ function for `T`.
+When a value `v` is matched against a pattern `T(x1,...,xn)`, if `Match.extract(::Type{T}, ::Val{n}, _)`
+is defined for type `T` and arity `n`, `extract(T, Val(n), v)` is called and the result is then matched
+against the tuple pattern `(x1,...,xn)`. The value `v` being matched need not be of type `T`.
+If the result of the `extract` call is `nothing` or does not match `(x1,...,xn)`, then the match fails.
+If `extract` is not defined for `T`, the value `v` is checked against the struct type `T`, as usual,
+with its fields matched against the subpatterns `x1`, ..., `xn`.
+
+For example, to match a pair of numbers using polar coordinates, extracting the radius and angle,
+you could define:
+```julia
+struct Polar end
+function Match.extract(::Type{Polar}, ::Val{2}, p::Tuple{<:Number,<:Number})
+    x, y = p
+    return (sqrt(x^2 + y^2), atan(y, x))
+end
+```
+This definition allows you to use a new `Polar` pattern:
+```julia
+@match (1,1) begin
+    Polar(r,θ) => @assert r == sqrt(2) && θ == π / 4
+end
+```
+
+The `extract` function should return either a tuple of values to be matched by the subpatterns
+or return `nothing`. Named parameters are not supported.
+
+Extractors can also be used to ignore or transform fields of existing types during matching.
+For example, this extractor ignores the `annos` field of the `AddExpr` type:
+```julia
+struct AddExpr
+    left
+    right
+    annos
+end
+function Match.extract(::Type{AddExpr}, ::Val{2}, e::AddExpr)
+    return (e.left, e.right)
+end
+@match AddExpr(x, y) = node
+```
+
+Extractors allow you to abstract from the concrete implementation of the struct type. For example, they
+can be used to implement more user-friendly pattern matching for types defined with `SumTypes.jl` or
+other packages.
+
 ## Differences from previous versions of `Match.jl`
 
 * If no branches are matched, throws `MatchFailure` instead of returning nothing.

src/Match.jl

@@ -247,6 +247,19 @@ struct MatchFailure <: Exception
     value
 end
 
+"""
+    extract(T::Type, ::Val{n}, value)
+
+Override matching for type `T`, destructuring `value` into its component fields.
+
+Given a struct pattern `T(p1,...,pn)`, if `extract(T, ::Val{n}, v)` is implemented for type
+`T` and arity `n`, it is called and the result will be matched against the tuple pattern
+`(p1,...,pn)`.
+
+The function should return either a tuple of the correct arity, or `nothing` if the match should fail.
+"""
+function extract end
+
 # const fields only suppored >= Julia 1.8
 macro _const(x)
     (VERSION >= v"1.8") ? Expr(:const, esc(x)) : esc(x)

src/binding.jl

@@ -95,6 +95,9 @@ end
 function gentemp(p::BoundFetchLengthPattern)::Symbol
     gensym(string("length(", simple_name(p.input), ")"))
 end
+function gentemp(p::BoundFetchExtractorPattern)::Symbol
+    gensym(string("extract(", p.extractor, ", ", simple_name(p.input), ")"))
+end
 
 #
 # The following are special bindings used to handle the point where
@@ -227,7 +230,7 @@ function bind_pattern!(
         # struct pattern.
         # TypeName(patterns...)
         T = source.args[1]
-        subpatterns = source.args[2:length(source.args)]
+        subpatterns = source.args[2:end]
         len = length(subpatterns)
         named_fields = [pat.args[1] for pat in subpatterns if is_expr(pat, :kw)]
         named_count = length(named_fields)
@@ -242,53 +245,84 @@ function bind_pattern!(
         match_positionally = named_count == 0
 
         # bind type at macro expansion time
-        pattern0, assigned = bind_pattern!(location, :(::($T)), input, binder, assigned)
-        bound_type = (pattern0::BoundTypeTestPattern).type
-        patterns = BoundPattern[pattern0]
-        field_names::Tuple = match_fieldnames(bound_type)
-        if match_positionally && len != length(field_names)
-            error("$(location.file):$(location.line): The type `$bound_type` has " *
-                  "$(length(field_names)) fields but the pattern expects $len fields.")
-        end
+        bound_type = bind_type(location, T, input, binder)
 
-        for i in 1:len
-            pat = subpatterns[i]
-            if match_positionally
-                field_name = field_names[i]
-                pattern_source = pat
-            else
-                @assert pat.head == :kw
-                field_name = pat.args[1]
-                pattern_source = pat.args[2]
-                if !(field_name in field_names)
-                    error("$(location.file):$(location.line): Type `$bound_type` has " *
-                          "no field `$field_name`.")
+        # Check if there is an extractor method for the pattern type.
+        extractor_sig = (Type{bound_type}, Val{len}, Any,)
+        is_extractor = !isempty(Base.methods(Match.extract, extractor_sig))
+
+        if is_extractor
+            # Call Match.extract(T) and match the result against the tuple of subpatterns.
+            # TODO remove once named tuples are supported
+            @assert match_positionally error("$(location.file):$(location.line): Named arguments are not supported for extractor pattern `$source`.")
+            conjuncts = BoundPattern[]
+            fetch = BoundFetchExtractorPattern(location, source, input, bound_type, len, Any)
+            extractor_temp = push_pattern!(conjuncts, binder, fetch)
+            tuple_source = Expr(:tuple, subpatterns...)
+            subpattern, assigned = bind_pattern!(location, tuple_source, extractor_temp, binder, assigned)
+            push!(conjuncts, subpattern)
+            pattern = BoundAndPattern(location, source, conjuncts)
+        else
+            # Use the field-by-field match.
+            conjuncts = BoundPattern[]
+
+            if isabstracttype(bound_type)
+                if match_positionally
+                    error("$(location.file):$(location.line): The type `$bound_type` is an abstract type. Consider defining an extractor `Match.extract(::Type{$bound_type`, ::Val{$len}, _)`.")
+                else
+                    error("$(location.file):$(location.line): The type `$bound_type` is an abstract type. Struct patterns can only be used with concrete types.")
                 end
             end
 
-            field_type = nothing
-            if field_name == match_fieldnames(Symbol)[1]
-                # special case Symbol's hypothetical name field.
-                field_type = String
-            else
-                for (fname, ftype) in zip(Base.fieldnames(bound_type), Base.fieldtypes(bound_type))
-                    if fname == field_name
-                        field_type = ftype
-                        break
+            field_names::Tuple = match_fieldnames(bound_type)
+
+            if match_positionally && len != length(field_names)
+                error("$(location.file):$(location.line): The type `$bound_type` has " *
+                        "$(length(field_names)) fields but the pattern expects $len fields.")
+            end
+
+            pattern0 = BoundTypeTestPattern(location, T, input, bound_type)
+            push!(conjuncts, pattern0)
+
+            for i in 1:len
+                pat = subpatterns[i]
+                if match_positionally
+                    field_name = field_names[i]
+                    pattern_source = pat
+                else
+                    @assert pat.head == :kw
+                    field_name = pat.args[1]
+                    pattern_source = pat.args[2]
+                    if !(field_name in field_names)
+                        error("$(location.file):$(location.line): Type `$bound_type` has " *
+                                "no field `$field_name`.")
                     end
                 end
+
+                field_type = nothing
+                if field_name == match_fieldnames(Symbol)[1]
+                    # special case Symbol's hypothetical name field.
+                    field_type = String
+                else
+                    for (fname, ftype) in zip(Base.fieldnames(bound_type), Base.fieldtypes(bound_type))
+                        if fname == field_name
+                            field_type = ftype
+                            break
+                        end
+                    end
+                end
+                @assert field_type !== nothing
+
+                fetch = BoundFetchFieldPattern(location, pattern_source, input, field_name, field_type)
+                field_temp = push_pattern!(conjuncts, binder, fetch)
+                bound_subpattern, assigned = bind_pattern!(
+                    location, pattern_source, field_temp, binder, assigned)
+                push!(conjuncts, bound_subpattern)
             end
-            @assert field_type !== nothing
 
-            fetch = BoundFetchFieldPattern(location, pattern_source, input, field_name, field_type)
-            field_temp = push_pattern!(patterns, binder, fetch)
-            bound_subpattern, assigned = bind_pattern!(
-                location, pattern_source, field_temp, binder, assigned)
-            push!(patterns, bound_subpattern)
+            pattern = BoundAndPattern(location, source, conjuncts)
         end
 
-        pattern = BoundAndPattern(location, source, patterns)
-
     elseif is_expr(source, :(&&), 2)
         # conjunction: `(a && b)` where `a` and `b` are patterns.
         subpattern1 = source.args[1]
@@ -355,6 +389,11 @@ function bind_pattern!(
     elseif is_expr(source, :tuple) || is_expr(source, :vect)
         # array or tuple
         subpatterns = source.args
+
+        if any(arg -> is_expr(arg, :parameters), subpatterns)
+            error("$(location.file):$(location.line): Cannot mix named and positional parameters in pattern `$source`.")
+        end
+
         splat_count = count(s -> is_expr(s, :...), subpatterns)
         if splat_count > 1
             error("$(location.file):$(location.line): More than one `...` in " *
@@ -410,7 +449,7 @@ function bind_pattern!(
         pattern0, assigned = bind_pattern!(location, subpattern, input, binder, assigned)
         pattern1 = shred_where_clause(guard, false, location, binder, assigned)
         pattern = BoundAndPattern(location, source, BoundPattern[pattern0, pattern1])
-    
+
     elseif is_expr(source, :if, 2)
         # if expr end
         if !is_empty_block(source.args[2])

src/bound_pattern.jl

@@ -286,6 +286,23 @@ function Base.:(==)(a::BoundFetchLengthPattern, b::BoundFetchLengthPattern)
     a.input == b.input
 end
 
+# Fetch a value using the given extractor function into a temporary.  See
+# `BoundFetchFieldPattern` for the general idea of how these are used.
+struct BoundFetchExtractorPattern <: BoundFetchPattern
+    location::LineNumberNode
+    source::Any
+    input::Symbol
+    extractor::Type
+    arity::Int
+    type::Type
+end
+function Base.hash(a::BoundFetchExtractorPattern, h::UInt64)
+    hash((a.input, a.extractor, a.arity, 0xd7882f5b4888d335), h)
+end
+function Base.:(==)(a::BoundFetchExtractorPattern, b::BoundFetchExtractorPattern)
+    a.input == b.input && a.extractor == b.extractor && a.arity == b.arity
+end
+
 # Preserve the value of the expression into a temp.  Used
 # (1) to force the binding on both sides of an or-pattern to be the same (a phi), and
 # (2) to load the value of a `where` clause.

src/lowering.jl

@@ -40,7 +40,7 @@ function code(bound_pattern::BoundTypeTestPattern, binder::BinderContext)
             $string($(bound_pattern.type)), " at macro expansion time but ",
              $src, " later."))))
         push!(binder.assertions, Expr(:block, bound_pattern.location, :($test || $thrown)))
-        push!(binder.asserted_types, )
+        push!(binder.asserted_types, src)
     end
     :($(bound_pattern.input) isa $(bound_pattern.type))
 end
@@ -89,6 +89,9 @@ end
 function code(bound_pattern::BoundFetchExpressionPattern)
     code(bound_pattern.bound_expression)
 end
+function code(bound_pattern::BoundFetchExtractorPattern)
+    Expr(:call, Match.extract, bound_pattern.extractor, Val(bound_pattern.arity), bound_pattern.input)
+end
 
 # Return an expression that computes whether or not the pattern matches.
 function lower_pattern_to_boolean(bound_pattern::BoundPattern, binder::BinderContext)

src/pretty.jl

@@ -185,6 +185,15 @@ function pretty(io::IO, p::BoundFetchLengthPattern)
     pretty(io, p.input)
     print(io, ")")
 end
+function pretty(io::IO, p::BoundFetchExtractorPattern)
+    print(io, "extract(")
+    pretty(io, p.extractor)
+    print(io, ", Val(")
+    pretty(io, p.arity)
+    print(io, "), ")
+    pretty(io, p.input)
+    print(io, ")")
+end
 function pretty(io::IO, p::BoundFetchExpressionPattern)
     pretty(io, p.bound_expression)
 end

test/coverage.jl

@@ -400,6 +400,18 @@ end # of automaton
         end
     end
 
+    @testset "exercise dumpall 3" begin
+        devnull = IOBuffer()
+        Match.@match_dumpall devnull some_value begin
+            Diff(_) => 1
+            _ => 2
+        end
+        Match.@match_dump devnull some_value begin
+            Diff(_) => 1
+            _ => 2
+        end
+    end
+
     @testset "trigger some normally unreachable code 1" begin
         @test_throws ErrorException Match.gentemp(:a)