Note [Demand notation]

This Note should be kept up to date with the documentation of `-fstrictness`
in the user's guide.

For pretty-printing demands, we use quite a compact notation with some
abbreviations. Here's the BNF:

  card ::= B                        {}
        |  A                        {0}
        |  M                        {0,1}
        |  L                        {0,1,n}
        |  1                        {1}
        |  S                        {1,n}

  box  ::= !                        Unboxed
        |  <empty>                  Boxed

  d    ::= card sd                  The :* constructor, just juxtaposition
        |  card                     abbreviation: Same as "card card"

  sd   ::= box card                 @Poly box card@
        |  box P(d,d,..)            @Prod box [d1,d2,..]@
        |  Ccard(sd)                @Call card sd@

So, L can denote a 'Card', polymorphic 'SubDemand' or polymorphic 'Demand',
but it's always clear from context which "overload" is meant. It's like
return-type inference of e.g. 'read'.

An example of the demand syntax is 1!P(1!L,A), the demand of fst's argument.
See Note [Demand examples] for more examples and their semantics.

This is the syntax for demand signatures:

  div ::= <empty>      topDiv
       |  x            exnDiv
       |  b            botDiv

  sig ::= {x->dx,y->dy,z->dz...}<d1><d2><d3>...<dn>div
                  ^              ^   ^   ^      ^   ^
                  |              |   |   |      |   |
                  |              \---+---+------/   |
                  |                  |              |
             demand on free        demand on      divergence
               variables           arguments      information
           (omitted if empty)                     (omitted if
                                                no information)