This module is an extension to the Math::Symbolic module. A basic
familiarity with that module is required.
The Math::Symbolic::Custom::Pattern module implements pattern matching routines
on Math::Symbolic trees. The patterns itself are constructed from Math::Symbolic
trees with just a few variables which have a special meaning.

The module provides two interfaces. You can use the `new()` and `match()`
methods this class provides, or you can use the `to_pattern()` and
`is_of_form()` methods on any Math::Symbolic tree. (Exported by the
Math::Symbolic::Custom::Pattern::Export module. Refer to that module for
details on `is_of_form()`.)

You can construct a pattern from any Math::Symbolic tree. For sake of
simplicity, we will talk about a tree a+(b*c) even if that’s just its string
representation. The tree is really what is returned by
`Math::Symbolic->parse_from_string("a+(b*c)")`.

Suppose you call

`
`

`
my $pattern = Math::Symbolic::Custom::Pattern->new("a+(b*c)");
`

That creates a pattern that matches this exact tree. Calling

`
`

`
my $boolean = $pattern->match($tree);
`

on any Math::Symbolic tree `$tree` will result in `$boolean` being false
except if it is `"a+(b*c)"`.

So far so good. This isn’t impressive and the `is_identical()` method of
all Math::Symbolic trees does the same. (Except that the pattern matching is
about twice as fast.)

If you create a pattern from the following string, however, you get different
behaviour: `"VAR + (VAR*VAR)"`. Now, any variable may be in place of `a`,
`b`, and `c`. (`"a + (x*x)"`, `b + (b*b)`, ...)

You can match with named (but not literal) variables with the following
pattern string: `"VAR_first + (VAR_first*VAR_second)"` This matches
the tree `"a + (a*b)"`, but not `"a + (c*b)"` since the first variable
in the parenthesis of the second tree is not the same as the one outside the
parenthesis. Note that the variable `"b"` in both examples could have been
any variable, since `VAR_second` occurrs only once in the pattern.

Analogous to the general `VAR` and named `VAR_foo` pattern elements, you may
use `TREE` to match any subtree whatsoever or `TREE_foo` to match a named
tree. Example: The pattern `"TREE_a + 5*TREE_a"` matches the tree
`"sin(b+c) + 5*sin(b+c)"`, but not `"sin(b+c) + 5*cos(b+c)"`. Beware of the
fact that the trees `"sin(b+c)"` and `"sin(c+b)"` would not be the same
either. Though mathematically equivalent, they do not have the same internal
representation. Canonicalizing the internal representation is simple in this
example, but is impossible in the general case, so just take care.

Finally, what works with variables and general trees also works with constants.
You may specify the pattern `"CONST_foo * a + atan(CONST_foo)"`. This matches
`"0.5*a + atan(0.5)"`, but does not match `"2*a + atan(0.5)"` since the
named constants are not equal. The general form `CONST` works as a wildcard
for any constants.