Merge remote-tracking branch 'willow/compromise-interface' into compromise-interface

Author: shashi

README.md

@@ -9,62 +9,69 @@ You should define the following methods for an expression tree type `T` with sym
 with TermInterface.jl, and therefore with [SymbolicUtils.jl](https://github.com/JuliaSymbolics/SymbolicUtils.jl) 
 and [Metatheory.jl](https://github.com/0x0f0f0f/Metatheory.jl).
 
-#### `istree(x::T)` or `istree(x::Type{T})`
+#### `isexpr(x::T)` 
 
-Check if `x` represents an expression tree. If returns true,
-it will be assumed that `operation(::T)` and `arguments(::T)`
-methods are defined. Definining these three should allow use
-of `SymbolicUtils.simplify` on custom types. Optionally `symtype(x)` can be
-defined to return the expected type of the symbolic expression.
+Returns `true` if `x` is an expression tree (an S-expression). If true, `head`
+and `children` methods must be defined for `x`.
 
+#### `iscall(x::T)`
 
-#### `exprhead(x)`
+Returns `true` if `x` is a function call expression. If true, `operation`, `arguments` must also be defined for `x::T`.
 
-If `x` is a term as defined by `istree(x)`, `exprhead(x)` must return a symbol,
-corresponding to the head of the `Expr` most similar to the term `x`.
-If `x` represents a function call, for example, the `exprhead` is `:call`.
-If `x` represents an indexing operation, such as `arr[i]`, then `exprhead` is `:ref`.
-Note that `exprhead` is different from `operation` and both functions should 
-be defined correctly in order to let other packages provide code generation 
-and pattern matching features. 
 
-#### `operation(x::T)`
+#### `head(x)`
 
-Returns the head (a function object) performed by an expression
-tree. Called only if `istree(::T)` is true. Part of the API required
-for `simplify` to work. Other required methods are `arguments` and `istree`
+Returns the head of the S-expression.
 
-#### `arguments(x::T)`
+#### `children(x)`
 
-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`
+Returns the children (aka tail) of the S-expression.
 
-In addition, the methods for `Base.hash` and `Base.isequal` should also be implemented by the types for the purposes of substitution and equality matching respectively.
 
-#### `similarterm(t::MyType, f, args, symtype=T; metadata=nothing, exprhead=exprhead(t))`
+#### `operation(x)`
 
-Or `similarterm(t::Type{MyType}, f, args, symtype=T; metadata=nothing, exprhead=:call)`.
+Returns the function a function call expression is calling. `iscall(x)` must be
+true as a precondition.
 
-Construct a new term with the operation `f` and arguments `args`, the term should be similar to `t` in type. if `t` is a `SymbolicUtils.Term` object a new Term is created with the same symtype as `t`. If not, the result is computed as `f(args...)`. Defining this method for your term type will reduce any performance loss in performing `f(args...)` (esp. the splatting, and redundant type computation). T is the symtype of the output term. You can use `SymbolicUtils.promote_symtype` to infer this type. The `exprhead` keyword argument is useful when creating `Expr`s.
+#### `arguments(x)`
+
+Returns the arguments to the function call in a function call expression.
+`iscall(x)` must be true as a precondition.
+
+#### `maketerm(T, head, children, type=nothing, metadata=nothing)`
+
+Constructs an expression. `T` is a constructor type, `head` and `children` are
+the head and tail of the S-expression, `type` is the `type` of the S-expression.
+`metadata` is any metadata attached to this expression.
+
+Note that `maketerm` may not necessarily return an object of type `T`. For example,
+it may return a representation which is more efficient.
+
+This function is used by term-manipulation routines to construct terms generically.
+In these routines, `T` is usually the type of the input expression which is being manipulated.
+For example, when a subexpression is substituted, the outer expression is re-constructed with
+the sub-expression. `T` will be the type of the outer expression.
+
+Packages providing expression types _must_ implement this method for each expression type.
+
+If your types do not support type information or metadata, you still need to accept
+these arguments and may choose to not use them.
 
 ### Optional
 
-#### `unsorted_arguments(x)`
+#### `arity(x)`
+
+When `x` satisfies `iscall`, returns the number of arguments of `x`.
+Implicitly defined if `arguments(x)` is defined.
 
-If x is a term satisfying `istree(x)` and your term type `T` provides
-an optimized implementation for storing the arguments, this function can 
-be used to retrieve the arguments when the order of arguments does not matter 
-but the speed of the operation does. Defaults to `arguments(x)`.
 
-#### `symtype(x)`
+#### `metadata(x)`
 
-The supposed type of values in the domain of x. Tracing tools can use this type to
-pick the right method to run or analyse code.
+Returns the metadata attached to `x`.
 
-This defaults to `typeof(x)` if `x` is numeric, or `Any` otherwise.
-For the types defined in this SymbolicUtils.jl, namely `T<:Symbolic{S}` it is `S`.
+#### `symtype(expr)`
 
+Returns the symbolic type of `expr`. By default this is just `typeof(expr)`.
 Define this for your symbolic types if you want `SymbolicUtils.simplify` to apply rules
 specific to numbers (such as commutativity of multiplication). Or such
 rules that may be implemented in the future.

src/TermInterface.jl

@@ -8,14 +8,6 @@ must also be defined for `x`.
 iscall(x) = false
 export iscall
 
-Base.@deprecate_binding istree iscall
-"""
-   istree(x)
-
-Alias of `iscall`
-"""
-istree
-
 """
     isexpr(x)
 Returns `true` if `x` is an expression tree (an S-expression). If true, `head` and `children` methods must be defined for `x`.
@@ -119,7 +111,7 @@ end
 
 
 """
-    maketerm(T, head, children, type, metadata)
+    maketerm(T, head, children, type=nothing, metadata=nothing)
 
 Constructs an expression. `T` is a constructor type, `head` and `children` are
 the head and tail of the S-expression, `type` is the `type` of the S-expression.

src/utils.jl

@@ -2,15 +2,15 @@
   is_operation(f)
 
 Returns a single argument anonymous function predicate, that returns `true` if and only if
-the argument to the predicate satisfies `istree` and `operation(x) == f` 
+the argument to the predicate satisfies `iscall` and `operation(x) == f` 
 """
-is_operation(f) = @nospecialize(x) -> istree(x) && (operation(x) == f)
+is_operation(f) = @nospecialize(x) -> iscall(x) && (operation(x) == f)
 export is_operation
 
 
 """
   node_count(t)
-Count the nodes in a symbolic expression tree satisfying `istree` and `arguments`.
+Count the nodes in a symbolic expression tree satisfying `isexpr` and `arguments`.
 """
-node_count(t) = istree(t) ? reduce(+, node_count(x) for x in arguments(t), init = 0) + 1 : 1
+node_count(t) = isexpr(t) ? reduce(+, node_count(x) for x in children(t); init=0) + 1 : 1
 export node_count