Confused by the opts : OptionsPattern[ ] pattern

Question

I'm trying to make sense of the syntax in the clause opts:OptionsPattern[], as found in this standard "rule-based" (pseudo-)function definition pattern:

aFunction[a1_, a2_, a3_, opts:OptionsPattern[]] := ...

I've spent the last couple of hours chasing one reference after another in the Mathematica documentation, and getting nowhere. In fact, I now have a few more questions than the ones I began with (and remain unanswered).

Let me try to distill all these questions into two.

First, does : have a unique, consistent interpretation? If it does I can't figure it out. It seems to have a completely different meaning depending on the context. Here's a stark illustration: suppose that a, b, c, and d are unbound symbols. Then, of the following expressions, the first three are valid, but the last one is not (i.e. the front end throws an exception):

    b : c : d
    b :(c : d)
a :(b : c): d
   (b : c): d

I was not prepared for this! (At worst, I expected non-associativity, as found with the - or / operators, for example; IOW, at worst I expected that (b:c):d would be merely different from b:(c:d), not that it would throw an exception.)

Second, is the syntax of opts:OptionsPattern[]

aFunction[a1_, a2_, a3_, opts:OptionsPattern[]] := ...

a special form (i.e. not deducible from any other syntactic rule in the language)? It appears so to me, because I cannot produce any useful expressions with the symbol:defaultValue pattern among the formal arguments of a "rule-based" (pseudo-)function definition¹.

So a different way to formulate the second question is: is there any useful application of the form

aFunction[..., symbol:defaultValue] := ...

...in which defaultValue is something other than OptionsPattern[]?

Note: I know the use-case for the similar-looking form (note the _)

aFunction[..., symbol_:defaultValue] := ...

I'm not asking about it.

---

_{¹ For example:}

foo[x:8] := x;

foo[]
(* foo[] *)

foo[3]
(* foo[3] *)

_{Contrast the "do-nothing" definition above with this one:}

frobozz[x:OptionsPattern[]] := x;

frobozz[]
(* Sequence[] *)

frobozz[1]
(* frobozz[1] *)

frobozz[quux->frobnitz]
(* quux->frobnitz *)

Answer 1

Re 1: As documented in Operator Input Forms, colon represents two different operations:

symb:expr   Pattern[symb, expr]
patt:expr   Optional[patt, expr]

If you look at the FullForm of your first three examples, you'll see that they follow these forms. The fourth example arguably is a bug.

Re 2) No, opts:OptionsPattern[] is not a special form. From the rules given above, rules opts: OptionsPattern[] is the first case, assigning the pattern OptionsPattern[] to the symbol opts. OptionsPattern[] is itself a particular kind of pattern, just like _, Except, and KeyValuePattern are particular kinds of patterns. What sets it slightly apart from other patterns is that it sets up special rules for using OptionValue on the RHS of the rule.

More generally, about a year and half ago (so I think for 10.4), I got so fed up with the documentation of OptionsPattern and OptionsValue that I led a mini project to completely rewrite their pages. I think reading both the details and the new examples will give you a lot more insight into this idiom.