added documentation

Author: Bumblebee00

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

@@ -243,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`).