added defslot documentation to rewrite.md

Author: Bumblebee00

docs/src/manual/rewrite.md

@@ -25,14 +25,14 @@ r1(sin(2z))
 
 The `@rule` macro takes a pair of patterns -- the _matcher_ and the _consequent_ (`@rule matcher => consequent`). If an expression matches the matcher pattern, it is rewritten to the consequent pattern. `@rule` returns a callable object that applies the rule to an expression.
 
-`~x` in the example is what is a **slot variable** named `x`. In a matcher pattern, slot variables are placeholders that match exactly one expression. When used on the consequent side, they stand in for the matched expression. If a slot variable appears twice in a matcher pattern, all corresponding matches must be equal (as tested by `Base.isequal` function). Hence this rule says: if you see something added to itself, make it twice of that thing, and works as such.
+`~x` in the example is what is a **slot variable** named `x`. In a matcher pattern, slot variables are placeholders that match exactly one expression. When used on the consequent side, they stand in for the matched expression. If a slot variable appears twice in a matcher pattern, all corresponding matches must be equal (as tested by `Base.isequal` function).
 
 If you try to apply this rule to an expression with triple angle, it will return `nothing` -- this is the way a rule signifies failure to match.
-```jldoctest rewrite
-r1(sin(3z)) === nothing
+```julia
+r1(sin(3z))
 
 # output
-true
+nothing
 ```
 
 Slot variable (matcher) is not necessary a single variable
@@ -44,25 +44,47 @@ r1(sin(2*(w-z)))
 2cos(w - z)*sin(w - z)
 ```
 
-but it must be a single expression
+Rules are of course not limited to single slot variable
 
 ```jldoctest rewrite
-r1(sin(2*(w+z)*(α+β))) === nothing
+r2 = @rule sin(~x + ~y) => sin(~x)*cos(~y) + cos(~x)*sin(~y);
+
+r2(sin(α+β))
 
 # output
-true
+sin(β)*cos(α) + cos(β)*sin(α)
 ```
 
-Rules are of course not limited to single slot variable
-
+Let's say you want to catch the coefficents of a second degree polynomial in z. You can do that with:
 ```jldoctest rewrite
-r2 = @rule sin(~x + ~y) => sin(~x)*cos(~y) + cos(~x)*sin(~y);
+c2d = @rule ~a + ~b*z + ~c*z^2 => (~a, ~b, ~c)
 
-r2(sin(α+β))
+c2d(3 + 2z + 5z^2)
+# output
+(3, 2, 5)
+```
+Great! But if you try:
+```julia
+c2d(3 + 2z + z^2)
 
+#output
+nothing
+```
+the rule is not applied. This is because in the input polynomial there isnt a multiplication in front of the `z^2`. If you want to solve this you must use **defslot variables**, with syntax `~!a`:
+```jldoctest rewrite
+c2d = @rule ~!a + ~!b*z + ~!c*z^2 => (~a, ~b, ~c)
+
+c2d(3 + 2z + z^2)
 # output
-sin(β)*cos(α) + cos(β)*sin(α)
+(3, 2, 1)
 ```
+They work like normal slot variables, but if not present take a default value depending on the operation they are in, in the above example `~b = 1`. Currently defslot variables can be definied in:
+
+Operation | Default value
+----------|--------------
+multiplication `*` | 1
+addition `+` | 0
+2nd argument of `^` | 1
 
 If you want to match a variable number of subexpressions at once, you will need a **segment variable**. `~~xs` in the following example is a segment variable:
 

src/rule.jl

@@ -248,24 +248,6 @@ If an expression matches LHS entirely, then it is rewritten to the pattern in th
 Slot, DefSlot and Segment variables 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`).
@@ -310,7 +292,7 @@ julia> r(sin(2a)^2 + cos(a)^2)
 
 **DefSlot**:
 
-A DefSlot variable is written as `~!x`. Works like a normal slot, but can also take additional values if not present in the expression.
+A DefSlot variable is written as `~!x`. Works like a normal slot, but can also take default values if not present in the expression.
 
 _Example in power:_
 ```julia
@@ -337,10 +319,11 @@ julia> r_sum(x)
 ```
 
 Currently DefSlot is implemented in:
-Operation | Default value
+
+Operation | Default value<br>
 ----------|--------------
-* | 1
-+ | 0
+\\* | 1
+\\+ | 0
 2nd argument of ^ | 1
 
 **Segment**:
@@ -410,6 +393,24 @@ true
 Note that this is syntactic sugar and that it is the same as something like
 `@rule ~x => f(~x) ? ~x : nothing`.
 
+**Debugging Rules**:
+Note that if the RHS is a single tilde `~`, then the rule returns a a dictionary of all [slot variable, expression matched], this is useful for debugging.
+
+_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
+```
+
 **Context**:
 
 _In predicates_: Contextual predicates are functions wrapped in the `Contextual` type.