Merge pull request #8 from SymbolicML/safer-operator-extending

Safer way of extending user-defined operators

Author: MilesCranmer

Project.toml

@@ -1,7 +1,7 @@
 name = "DynamicExpressions"
 uuid = "a40a106e-89c9-4ca8-8020-a735e8728b6b"
 authors = ["MilesCranmer <miles.cranmer@gmail.com>"]
-version = "0.3.2"
+version = "0.4.0"
 
 [deps]
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"

README.md

@@ -159,19 +159,28 @@ x1 = Node(String; feature=1)
 This node, will be used to index input data (whatever it may be) with either `data[feature]` (1D abstract arrays) or `selectdim(data, 1, feature)` (ND abstract arrays). Let's now define some operators to use:
 
 ```julia
-my_string_func(x::String) = "Hello $x"
+my_string_func(x::String) = "ello $x"
 
 operators = GenericOperatorEnum(;
     binary_operators=[*],
-    unary_operators=[my_string_func],
-    extend_user_operators=true)
+    unary_operators=[my_string_func]
+)
+```
+
+Now, let's extend our operators to work with the
+expression types used by `DynamicExpressions.jl`:
+
+```julia
+@extend_operators operators
 ```
 
 Now, let's create an expression:
 
 ```julia
-tree = x1 * " World!"
-tree(["Hello", "Me?"])
+tree = "H" * my_string_func(x1)
+# ^ `(H * my_string_func(x1))`
+
+tree(["World!", "Me?"])
 # Hello World!
 ```
 
@@ -202,7 +211,8 @@ vec_add(x, y) = x .+ y
 vec_square(x) = x .* x
 
 # Set up an operator enum:
-operators = GenericOperatorEnum(;binary_operators=[vec_add], unary_operators=[vec_square], extend_user_operators=true)
+operators = GenericOperatorEnum(;binary_operators=[vec_add], unary_operators=[vec_square])
+@extend_operators operators
 
 # Construct the expression:
 tree = vec_add(vec_add(vec_square(x1), c2), c1)

docs/src/types.md

@@ -13,16 +13,35 @@ OperatorEnum
 Construct this operator specification as follows:
 
 ```@docs
-OperatorEnum(; binary_operators, unary_operators, enable_autodiff)
+OperatorEnum(; binary_operators=[], unary_operators=[], enable_autodiff::Bool=false, define_helper_functions::Bool=true)
 ```
 
 This is just for scalar real operators. However, you can use
 the following for more general operators:
 
 ```@docs
-GenericOperatorEnum(; binary_operators=[], unary_operators=[], extend_user_operators::Bool=false)
+GenericOperatorEnum(; binary_operators=[], unary_operators=[], define_helper_functions::Bool=true)
 ```
 
+By default, these operators will define helper functions for constructing trees,
+so that you can write `Node(;feature=1) + Node(;feature=2)` instead of
+`Node(1, Node(;feature=1), Node(;feature=2))` (assuming `+` is the first operator).
+You can turn this off with `define_helper_functions=false`.
+
+For other operators *not* found in `Base`, including user-defined functions, you may
+use the `@extend_operators` macro:
+
+```@docs
+@extend_operators operators
+```
+
+This will extend the operators you have passed to work with `Node` types, so that
+it is easier to construct expression trees.
+
+Note that you are free to use the `Node` constructors directly.
+This is a more robust approach, and should be used when creating libraries
+which use `DynamicExpressions.jl`.
+
 ## Equations
 
 Equations are specified as binary trees with the `Node` type, defined

src/DynamicExpressions.jl

@@ -24,7 +24,8 @@ using Reexport
     get_constants,
     set_constants
 @reexport import .OperatorEnumModule: AbstractOperatorEnum
-@reexport import .OperatorEnumConstructionModule: OperatorEnum, GenericOperatorEnum
+@reexport import .OperatorEnumConstructionModule:
+    OperatorEnum, GenericOperatorEnum, @extend_operators
 @reexport import .EvaluateEquationModule: eval_tree_array, differentiable_eval_tree_array
 @reexport import .EvaluateEquationDerivativeModule:
     eval_diff_tree_array, eval_grad_tree_array