Merge pull request #774 from Bumblebee00/rule_returns_matches_ditionary

added functionality to return matches dictionary

Author: AayushSabharwal

docs/src/manual/rewrite.md

@@ -97,6 +97,23 @@ Notice that the expression was autosimplified before application of the rule.
 2(2w + α + β)
 ```
 
+Note that writing a single tilde `~` as consequent, will make the rule return a dictionary of [slot variable, expression matched].
+
+```jldoctest rewrite
+r = @rule (~x + (~y)^(~m)) => ~
+
+r(z+w^α)
+
+# output
+Base.ImmutableDict{Symbol, Any} with 5 entries:
+  :MATCH => z + w^α
+  :m     => α
+  :y     => w
+  :x     => z
+  :____  => nothing
+
+```
+
 ### Predicates for matching
 
 Matcher pattern may contain slot variables with attached predicates, written as `~x::f` where `f` is a function that takes a matched expression and returns a boolean value. Such a slot will be considered a match only if `f` returns true.

src/rule.jl

@@ -163,6 +163,8 @@ function makeconsequent(expr)
         else
             return Expr(expr.head, map(makeconsequent, expr.args)...)
         end
+    elseif expr===:(~)
+        return :(__MATCHES__)
     else
         # treat as a literal
         return esc(expr)
@@ -241,6 +243,24 @@ If an expression matches LHS entirely, then it is rewritten to the pattern in th
 Segment (`~x`) and slot variables (`~~x`) on the RHS will substitute the result of the
 matches found for these variables in the LHS.
 
+If the RHS is a single tilde `~`, then the rule returns a a dictionary of
+[slot variable, expression matched].
+
+_Example:_
+
+```julia
+julia> r = @rule (~x + (~y)^(~m)) => ~
+~x + (~y) ^ ~m => (~)
+
+julia> r(a + b^2)
+Base.ImmutableDict{Symbol, Any} with 5 entries:
+  :MATCH => a + b^2
+  :m     => 2
+  :y     => b
+  :x     => a
+  :____  => nothing
+```
+
 **Slot**:
 
 A Slot variable is written as `~x` and matches a single expression. `x` is the name of the variable. If a slot appears more than once in an LHS expression then expression matched at every such location must be equal (as shown by `isequal`).

test/rewrite.jl

@@ -82,6 +82,22 @@ end
     @test r_mix((a + b)) === 2 #1+1
 end
 
+@testset "Return the matches dictionary" begin
+    r = @rule (~x + (~y)^2) => ~
+    res = r(a + b^2)
+    @test isa(res, Base.ImmutableDict)
+    @test res[:x] === a
+    @test res[:y] === b
+
+    r2 = @rule (~x + (~y)^(~m)) => (~) where ~m===2
+    @test isa(r2(a + b^2), Base.ImmutableDict)
+    @test r2(a + b^3)===nothing
+
+    r3 = @rule (~x + (~y)^(~m)) => ~m===2 ? (~) : ~x
+    @test isa(r3(a + b^2), Base.ImmutableDict)
+    @test r3(a + b^3)===a
+end
+
 using SymbolicUtils: @capture
 
 @testset "Capture form" begin