Suggestion for bang patterns documentation

[Brian Bloniarz]

I got confused by the GHC documentation recently, I was wondering how
it could be improved. From:
http://www.haskell.org/ghc/docs/latest/html/users_guide/bang-patterns.html

> A bang only really has an effect if it precedes a variable or wild-card pattern:
> f3 !(x,y) = [x,y]
> f4 (x,y)  = [x,y]
> Here, f3 and f4 are identical; putting a bang before a pattern that
> forces evaluation anyway does nothing.

The first sentence is true, but only in settings where the pattern is being
evaluated eagerly -- the bang in:
> f3 a = let !(x,y) = a in [1,x,y]
> f4 a = let (x,y) = a in [1,x,y]
has an effect.

The first time I read this, I took the first sentence to be a unqualified truth
and ended up thinking that !(x,y) was equivalent to (x,y) everywhere. Stuff
that comes later actually clarifies this, but I missed it.

What about making the distinction clear upfront? Something like:
> A bang in an eager pattern match only really has an effect if it precedes a variable
> or wild-card pattern:
> f3 !(x,y) = [x,y]
> f4 (x,y)  = [x,y]
> Because f4 _|_ will force the evaluation of the pattern match anyway, f3 and f4
> are identical; the bang does nothing.

It also might be a good idea to immediately follow this with the let/where usage:

> A bang can also preceed a let/where binding to make the pattern match strict. For example:
> let ![x,y] = e in b
> is a strict pattern...
(in the existing docs, let comes a bit later):

Just a thought. Hopefully someone can come up with a better way of
wording what I'm getting at.

Thanks,
-Brian

_________________________________________________________________
Windows Live™ Hotmail®…more than just e-mail. 
http://windowslive.com/howitworks?ocid=TXT_TAGLM_WL_t2_hm_justgotbetter_howitworks_022009