A.5.1 Patterns

Patterns stand for classes of expressions. They contain pattern objects which represent sets of possible expressions.

_	any expression
x_	any expression, given the name x
x:pattern	a pattern, given the name x
pattern ? test	a pattern that yields True when test is applied to its value
_h	any expression with head h
x_h	any expression with head h, given the name x
__	any sequence of one or more expressions
___	any sequence of zero or more expressions
x__ and x___	sequences of expressions, given the name x
__h and ___h	sequences of expressions, each with head h
x__h and x___h	sequences of expressions with head h, given the name x
x_:v	an expression with default value v
x_h:v	an expression with head h and default value v
x_.	an expression with a globally defined default value
Optional[x_h]	an expression that must have head h, and has a globally defined default value
Except[c]	any expression except one that matches c
Except[c, pattern]	any expression matching pattern, except one that matches c
pattern..	a pattern repeated one or more times
pattern...	a pattern repeated zero or more times
| | ...	a pattern which matches at least one of the
pattern /; cond	a pattern for which cond evaluates to True
HoldPattern[pattern]	a pattern not evaluated
Verbatim[expr]	an expression to be matched verbatim

When several pattern objects with the same name occur in a single pattern, all the objects must stand for the same expression. Thus f[x_, x_] can stand for f[2, 2] but not f[2, 3].

In a pattern object such as _h, the head h can be any expression, but cannot itself be a pattern.

A pattern object such as x__ stands for a sequence of expressions. So, for example, f[x__] can stand for f[a, b, c], with x being Sequence[a, b, c]. If you use x, say in the result of a transformation rule, the sequence will be spliced into the function in which x appears. Thus g[u, x, u] would become g[u, a, b, c, u].

When the pattern objects x_:v and x_. appear as arguments of functions, they represent arguments which may be omitted. When the argument corresponding to x_:v is omitted, x is taken to have value v. When the argument corresponding to x_. is omitted, x is taken to have a default value that is associated with the function in which it appears. You can specify this default value by making assignments for Default[f] and so on.

Default[f]	default value for x_. when it appears as any argument of the function f
Default[f, n]	default value for x_. when it appears as the n argument (negative n count from the end)
Default[f, n, tot]	default value for the n argument when there are a total of tot arguments

A pattern like f[x__, y__, z__] can match an expression like f[a, b, c, d, e] with several different choices of x, y and z. The choices with x and y of minimum length are tried first. In general, when there are multiple __ or ___ in a single function, the case that is tried first takes all the __ and ___ to stand for sequences of minimum length, except the last one, which stands for "the rest" of the arguments.

When x_:v or x_. are present, the case that is tried first is the one in which none of them correspond to omitted arguments. Cases in which later arguments are dropped are tried next.

Orderless	f[x, y] and f[y, x] are equivalent
Flat	f[f[x], y] and f[x, y] are equivalent
OneIdentity	f[x] and x are equivalent

Pattern objects like x_ can represent any sequence of arguments in a function f with attribute Flat. The value of x in this case is f applied to the sequence of arguments. If f has the attribute OneIdentity, then e is used instead of f[e] when x corresponds to a sequence of just one argument.