# How is pattern specificity decided?

Mathematica has a notion of pattern specificity, which is a partial ordering on patterns.

The rules (e.g. DownValues, SubValues, etc) attached to a symbol are linearly ordered, with this ordering determined by the order in which the values and the specificity ordering.

During evaluation, the rules are tried according to this ordering.

As each rule is added, if its left hand side is more specific than the left hand side of an existing rule, it is inserted before the first such existing rule, and otherwise it is added at the end. This is briefly described in the Mathematica documentation, at http://reference.wolfram.com/mathematica/tutorial/PatternsAndTransformationRules.html.

The general intention of pattern specificity is that it corresponds to the range of expressions that the pattern could match. The actual implementation of pattern specificity in Mathematica is much weaker, of course; this ideal notion of specificity would of course be undecidable. As an example, _?f and _?g are considered incomparable for any expressions f and g even though in the ideal partial ordering _?True& would be less specific than _?False&. To my knowledge, pattern specificity is a weakening of the ideal notion of specificity (that is, if p is considered more specific than q, then p matches a strict subset of the expressions that q matches), although there may well be some interesting counterexamples!

One can 'experimentally' examine the partial ordering of pattern specificity using the following commands:

SetAttributes[{PatternsComparableQ, PatternsOrderedQ}, HoldAll]
PatternsComparableQ[f_, g_] := Module[{x, y},
x[HoldPattern[f]] := 1;
x[HoldPattern[g]] := 2;
y[HoldPattern[g]] := 3;
y[HoldPattern[f]] := 4;
DownValues[x][[1, 1, 1, 1]] === DownValues[y][[1, 1, 1, 1]]
]
PatternsOrderedQ[_[f_, g_]] := Module[{x, y},
x[HoldPattern[f]] := 1;
x[HoldPattern[g]] := 2;
y[HoldPattern[g]] := 3;
y[HoldPattern[f]] := 4;
DownValues[x][[1, 1, 1, 1]] === DownValues[y][[1, 1, 1, 1]] === HoldPattern[f]
]
PatternsOrderedQ[x_] := OrderedQ[x, PatternsOrderedQ[{#1, #2}] &]


Now, my question:

How is pattern specificity determined in practice?

A perfect(!) answer might include an algorithm reproducing the results of PatternsComparableQ and PatternsOrderedQ above, without interacting with the state of the kernel via DownValues et al. I'd also be interested in pointers to documentation, or informal descriptions of the algorithm used.

(I'm also aware of InternalComparePatterns which I learnt about in this excellent answer to a related question, but as it is known to "make mistakes" and doesn't appear to actually be used in ordering the rules attached to symbols, I'm not sure it's relevant.)

-
This is a deep question. As a point of interest, are you aware of an example where InternalComparePatterns fails to distinguish patterns in the way that your test functions do? In other words is it plausible that this function or the mechanism behind it in fact is used? –  Mr.Wizard Jul 23 '12 at 8:13
This question made me wonder, are you still working on omath? –  Szabolcs Jul 23 '12 at 8:13
Is it really a partial order? I would argue that it is a total order, since MMA always orders patterns in some way. If it cannot determine algorithmic specificity, it uses temporal or lexicographic ordering (I think), which is another kind of specificity, after all. –  magma Jul 23 '12 at 9:07
@Mr. Wizard, InternalComparePatterns says that __ and (_)..` are each more specific than the other, while my 'experimental' approach above says they are incomparable. –  Scott Morrison Jul 23 '12 at 19:02
@magma, when you take into account the time order in which the rules are attached to a symbol, you can obtain a total ordering (as I mentioned in the question). It's pretty easy to see, by playing around with examples that the functions I show above appear to define a partial ordering. –  Scott Morrison Jul 23 '12 at 19:05