Merge pull request #66 from jverzani/matchpy

Matchpy

Project.toml

@@ -1,7 +1,7 @@
 name = "SimpleExpressions"
 uuid = "deba94f7-f32a-40ad-b45e-be020a5ded2f"
 authors = ["jverzani <[email protected]> and contributors"]
-version = "1.1.8"
+version = "1.1.9"
 
 [deps]
 CallableExpressions = "391672e0-bbe4-4ab4-8bc9-b89a79cbc2f0"

docs/src/index.md

@@ -104,7 +104,9 @@ The basic syntax for substitution is:
 
 The use of `:` to indicate the remaining value is borrowed from Julia's array syntax; it can also be either `nothing` or `missing`.
 
-For evaluation and substitution using positional arguments, all instances of symbolic variables and all instances of symbolic parameters are treated identically. To work with multiple symbolic parameters or variables, `replace` can be used to substitute in values for a specific variable.
+For evaluation and substitution using positional arguments, all instances of symbolic variables and all instances of symbolic parameters are treated identically.
+
+To work with multiple symbolic parameters or variables, `replace` can be used to substitute in values for a specific variable.
 
 * `replace(ex, args::Pair...)` to substitute in for either a variable, parameter, expression head, or symbolic expression (possibly with a wildcard). The pairs are specified as `variable_name => replacement_value`.
 * `ex(args::Pair...)` redirects to `replace(ex, args::Pair...)`
@@ -113,7 +115,7 @@ To illustrate, two or more variables can be used, as here:
 
 ```@example expressions
 @symbolic x
-@symbolic y  # both symbolic variables
+@symbolic y  # or SimpleExpressions.@symbolic_variables x y
 u = x^2 - y^2
 ```
 
@@ -131,9 +133,10 @@ v = replace(u, x=>1, y=>2) # the symbolic value ((1^2)-(2^2))
 v()                        # evaluates to -3
 ```
 
-The `replace` method is a bit more involved than illustrate. The `key => value` pairs have different dispatches depending on the value of the key. Above, the key is a `SymbolicVariable`, but the key can be
+The `replace` method is a bit more involved than illustrated. The `key => value` pairs have different dispatches depending on the value of the key. Above, the key is a `SymbolicVariable`, but the key can be:
 
 * A `SymbolicVariable` or `SymbolicParameter` in which case the simple substitution is applied, as just illustrated.
+
 * A function, like `sin`. In this case, a matching operation head is replaced by the replacement head. Eg. `sin => cos` will replace a `sin` call with a `cos` call.
 
 ```@example expressions
@@ -148,16 +151,27 @@ v = 1 + (x+1)^1 + 2*(x+1)^2 + 3*(x+1)^3
 replace(v, x+1 => x)
 ```
 
-
-* A symbolic expression *with* a *wildcard*. The **special** symbol `⋯`, when made into a symbolic variable via `@symbolic  ⋯` (where ` ⋯` is entered as `\cdots[tab]`) is treated as a wildcard for matching purposes. The `⋯` can be used in the replacement.
+* A symbolic expression *with* a *wildcard*. Wildcards have a naming convention using trailing underscores. One matches one value; two matches one or more values; three match 0, 1, or more values. In addition, the **special** symbol `⋯` (entered with `\cdots[tab]` is wild.
 
 ```@example expressions
 v = log(1 + x) + log(1 + x^2/2)
-@symbolic ⋯ # create wildcard
-replace(v, log(1 + ⋯) => log1p(⋯))
+@symbolic x_
+replace(v, log(1 + x_) => log1p(x_)) # log1p(x) + log1p((x ^ 2) / 2)
 ```
 
+Substitution uses `match(pattern, subject)` for expression matching with wildcards:
 
+```@example expressions
+subject, pattern = log(1 + x^2/2), log(1+x_)
+ms = match(pattern, subject)
+```
+
+The return value is `nothing` (for no match) or a collection of valid substitutions. Substituting one into the pattern should return the subject:
+
+```@example expressions
+σ = first(ms)
+pattern(σ...)
+```
 
 
 ## Symbolic containers
@@ -172,7 +186,7 @@ u(2, (1,2,3,4)) # 49
 
 This is relatively untested and almost certainly not fully featured. For example, only evaluation is allowed, not substitution (using `:`):
 
-```
+```@example expressions
 @symbolic x a
 u = sum(ai * x^(i-1) for (i,ai) in enumerate(a))
 u(2, [1,2,3])
@@ -249,12 +263,12 @@ x0 = 2
 x0 - u(x0) / du(x0)
 ```
 
-Here the product rule is used:
+Here the application of the product rule can be seen:
 
 ```@example expressions
 u = D(exp(x) * (sin(3x) + sin(101x)), x)
 ```
 
 #### Simplification
 
-No simplification is done so the expressions can quickly become unwieldy. There is `TermInterface` support, so--in theory--rewriting of expressions, as is possible with the `Metatheory.jl` package. The scaffolding is in place, but waits for the development version to be tagged.
+No simplification is done so the expressions can quickly become unwieldy. There is `TermInterface` support, so--in theory--rewriting of expressions, as is possible with the `Metatheory.jl` package, is supported. The scaffolding is in place, but waits for the development version to be tagged.

src/SimpleExpressions.jl

@@ -16,26 +16,29 @@ using CallableExpressions
 import TermInterface
 import TermInterface: iscall, operation, arguments, sorted_arguments,
     maketerm, is_operation, metadata
+using Combinatorics
 using CommonEq
-# export ≪, ≦, Eq, ⩵, ≶, ≷, ≫, ≧ # \ll, \leqq, \Equal,\lessgtr, \gtrless, \gg,\geqq
-
 
 export @symbolic
 
 include("types.jl")
 include("constructors.jl")
+include("decl.jl")
 include("equations.jl")
 include("terminterface.jl")
-#include("metatheory.jl")
 include("ops.jl")
 include("show.jl")
 include("introspection.jl")
 include("call.jl")
+include("matchpy.jl")
 include("replace.jl")
 include("comparison.jl")
 include("generators.jl")
 include("scalar-derivative.jl")
-include("simplify.jl")
 include("solve.jl")
 
+#include("simplify.jl")
+#include("metatheory.jl")
+
+
 end

src/constructors.jl

@@ -18,7 +18,7 @@ To call a symbolic expression regular call notation with positional arguments ar
 
 ## Example
 
-```julia
+```@example symbolic
 using SimpleExpressions
 @symbolic x p
 u = x^5 - x - 1
@@ -36,7 +36,7 @@ u(2, [1,2]) # 6  call is u(x, p)
 
 Calling with `nothing`, `missing`, or `:` in a slot *substitutes* in the specified value leaving a symbolic expression, possibly with no variable or parameter.
 
-```julia
+```@example symbolic
 @symbolic x p
 u = cos(x) - p*x
 u(nothing, 2)  # cos(x) - 2 * x
@@ -55,13 +55,13 @@ A symbolic equation, defined through `~`, may also be used to specify a left- an
 
 The main use is as an easier-to-type replacement for anonymous functions, though with differences:
 
-```julia
+```@example symbolic
 1 |> sin(x) |> x^2  # 0.708… from sin(1)^2
 u = cos(x) - p*x
 2 |> u(:, 3) # -6.4161…, a alternative to u(2,3)
 ```
 
-```julia
+```@example symbolic
 map(x^2, (1, 2)) # (1,4)
 ```
 
@@ -115,7 +115,7 @@ Using this is a convenience for *simple* cases. It is easy to run into idiosyncr
 
 Unlike functions, expressions are defined with variables at the time of definition, not when called. For example, with a clean environment:
 
-```julia
+```@example symbolic
 @symbolic x
 u = m*x + b    # errors, `m` not defined
 f(x) = m*x + b # ok
@@ -133,7 +133,7 @@ f(3)           # computing 3 * 3 + 4, using values of `m` and `b` when called
 Though one can make different symbolic variables, the basic call
 notation by position treats them as the same:
 
-```julia
+```@example symbolic
 @symbolic x
 @symbolic y    # both x, y are `SymbolicVariable` type
 u = x + 2y
@@ -142,13 +142,13 @@ u(3)           # 9 coming from 3 + 2*(3)
 
 However, this is only to simplify the call interface. Using *keyword* arguments allows evaluation with different values:
 
-```julia
+```@example symbolic
 u(;x=3, y=2)   # 7
 ```
 
 Using `replace`, we have:
 
-```julia
+```@example symbolic
 u(x=>3, y=>2)  # 3 + (2 * 2); evaluate with u(x=>3, y=>2)()
 ```
 
@@ -158,7 +158,7 @@ The underlying `CallableExpressions` object is directly called in the above mann
 
 The variables may be used as placeholders for containers, e.g.
 
-```julia
+```@example symbolic
 u = sum(xi*pi for (xi, pi) in zip(x,p))
 u((1,2),(3,4))  # 11
 ```
@@ -168,15 +168,15 @@ u((1,2),(3,4))  # 11
 
 Broadcasting a function call works as expected
 
-```julia
+```@example symbolic
 @symbolic x
 u = x^2
 u.((1,2)) # (1, 4)
 ```
 
 Symbolic expressions can also be constructed that will broadcast the call
 
-```julia
+```@example symbolic
 u = x.^2 .+ sin.(p)
 u((1,2),3)