enhance interface docs and tests

Author: MasonProtter

README.md

@@ -201,11 +201,16 @@ This section is for Julia package developers who may want to use the `simplify`
 
 Our intention is for SymbolicUtils to be useful even for packages with their own custom symbolic types which
 differ from those offered by SymbolicUtils. To this end, SymbolicUtils provides an interface to convert expression
-trees which have a an `operation`, (i.e. function to apply), `arguments` which the `operation` is applied to, and 
-optionally, a type which should `typeof(operation(arguments...))` should return if it were to be run.
+tree types which have 
+*  an `operation`, (i.e. function to apply)
+* `arguments` which the `operation` is applied to
+* `variable` types which are the atoms from which the expression tree is built 
+* optionally, a type which should `typeof(operation(arguments...))` should return if it were to be run.
 
+SymbolicUtils uses a function `to_symbolic` to convert aribtrarty types to it's own internal types. 
 
-The following functions should be defined for an expression tree type `T` to work with SymbolicUtils.jl
+The following methods should be defined for an expression tree type `T` with symbol types `S` to  work
+with SymbolicUtils.jl
 
 #### `istree(x::T)`
 
@@ -227,6 +232,17 @@ Returns the arguments (a `Vector`) for an expression tree.
 Called only if `istree(x)` is `true`. Part of the API required
 for `simplify` to work. Other required methods are `operation` and `istree`
 
+#### `to_symbolic(x::S)`
+Convert your variable type to a `SymbolicUtils.Variable`. Suppose you have
+```julia
+struct MySymbol
+   s::Symbol
+end
+```
+which could represent any type symbolically, then you would define 
+```julia
+SymbolicUtils.to_symbolic(s::MySymbol) = SymbolicUtils.Variable(s.s)
+```
 
 ### Optional
 
@@ -246,11 +262,11 @@ rules that may be implemented in the future.
 
 Returns the appropriate output type of applying `f` on arguments of type `arg_symtypes`.
 
-
 ### Example
 
 Suppose you were feeling the temptations of type piracy and wanted to make a quick and dirty
 symbolic library built on top of Julia's `Expr` type, e.g.
+
 ```julia
 for f ∈ [:+, :-, :*, :/, :^] #Note, this is type piracy!
     @eval begin
@@ -265,24 +281,25 @@ julia> ex = 1 + (:x - 2)
 :((+)(1, (-)(x, 2)))
 ```
 How can we use SymbolicUtils.jl to convert `ex` to `(-)(:x, 1)`? We simply implement `istree`,
-`operation` and `arguments` and we'll be off to the races:
+`operation`, `arguments` and `to_symbolic` and we'll be off to the races:
 ```julia
-using SymbolicUtils: istree, operation, arguments 
+using SymbolicUtils: Variable, istree, operation, arguments, to_symbolic
 
 SymbolicUtils.istree(ex::Expr) = ex.head == :call
 SymbolicUtils.operation(ex::Expr) = ex.args[1]
 SymbolicUtils.arguments(ex::Expr) = ex.args[2:end]
-
+SymbolicUtils.to_symbolic(s::Symbol) = Variable(s)
 
 julia> simplify(ex)
 (-1 + x)
 
-julia> dump(ans)
+julia> dump(simplify(ex))
 Term{Any}
   f: + (function of type typeof(+))
   arguments: Array{Any}((2,))
     1: Int64 -1
-    2: Symbol x
+    2: Variable{Any}
+      name: Symbol x
 ```
 this thing returns a `Term{Any}`, but it's not hard to convert back to `Expr`:
 ```julia
@@ -300,3 +317,17 @@ Expr
     2: Int64 -1
     3: Symbol x
 ```
+
+Now suppose we actaully wanted all `Symbol`s to be treated as `Real` numbers. We can simply define
+```
+SymbolicUtils.symtype(s::Symbol) = Real
+
+julia> dump(simplify(ex))
+Term{Real}
+  f: + (function of type typeof(+))
+  arguments: Array{Any}((2,))
+    1: Int64 -1
+    2: Variable{Real}
+      name: Symbol x
+```
+and now all our analysis is able to figure out that the `Term`s are `Number`s.

test/interface.jl

@@ -1,9 +1,10 @@
 using SymbolicUtils, Test
-using SymbolicUtils: Term, to_symbolic, istree, operation, arguments
+using SymbolicUtils: Term, Variable, to_symbolic, istree, operation, arguments
 
 SymbolicUtils.istree(ex::Expr) = ex.head == :call
 SymbolicUtils.operation(ex::Expr) = ex.args[1]
 SymbolicUtils.arguments(ex::Expr) = ex.args[2:end]
+SymbolicUtils.to_symbolic(s::Symbol) = Variable(s)
 
 for f ∈ [:+, :-, :*, :/, :^]
     @eval begin
@@ -15,10 +16,15 @@ end
 
 ex = 1 + (:x - 2)
 
-@test to_symbolic(ex) == Term{Any}(+, [1, Term{Any}(-, [:x, 2])])
+@test to_symbolic(ex) == Term{Any}(+, [1, Term{Any}(-, [Variable{Any}(:x), 2])])
 @test simplify(ex) == to_symbolic(-1 + :x)
 
 to_expr(t::Term) = Expr(:call, operation(t), to_expr.(arguments(t))...) 
+to_expr(s::Variable) = s.name
 to_expr(x) = x
 
-to_expr(simplify(ex))
+@test to_expr(simplify(ex)) == Expr(:call, +, -1, :x)
+
+SymbolicUtils.symtype(::Symbol) = Number
+
+