Merge pull request #783 from Bumblebee00/new_documentation

added defslot documentation to rewrite.md

Author: AayushSabharwal

docs/src/manual/rewrite.md

@@ -25,34 +25,34 @@ 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
-
+Slot variable (matcher) is not necessary a single variable:
 ```jldoctest rewrite
 r1(sin(2*(w-z)))
 
 # output
 2cos(w - z)*sin(w - z)
 ```
 
-but it must be a single expression
+And can also match a function:
+```julia
+r = @rule (~f)(z+1) => ~f
 
-```jldoctest rewrite
-r1(sin(2*(w+z)*(α+β))) === nothing
+r(sin(z+1))
 
 # output
-true
-```
+sin (generic function with 20 methods)
 
+```
 Rules are of course not limited to single slot variable
 
 ```jldoctest rewrite
@@ -64,6 +64,37 @@ r2(sin(α+β))
 sin(β)*cos(α) + cos(β)*sin(α)
 ```
 
+Now let's say you want to catch the coefficients of a second degree polynomial in z. You can do that with:
+```jldoctest rewrite
+c2d = @rule ~a + ~b*z + ~c*z^2 => (~a, ~b, ~c)
+
+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 isn't a multiplication in front of the `z^2`. For this you can 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
+(3, 2, 1)
+```
+They work like normal slot variables, but if they are not present they take a default value depending on the operation they are in, in the above example `~b = 1`. Currently defslot variables can be defined 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:
 
 ```jldoctest rewrite

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.