This module contains the lex actions that handle the layout rules. The way
it works is that the Parser monad keeps track of a stack of
LayoutContexts specifying the indentation of the layout blocks in scope.
For instance, consider the following incomplete (Haskell) program:

f x = x'
where
x' = case x of { True -> False; False -> ...

At the ... the layout context would be

[NoLayout, Layout 4, Layout 0]

The closest layout block is the one containing the case branches. This
block starts with an open brace ('{') and so doesn't use layout. The
second closest block is the where clause. Here, there is no open brace
so the block is started by the x' token which has indentation 4. Finally
there is a top-level layout block with indentation 0.

Documentation

Executed upon lexing a close brace ('}'). Exits the current layout
context. This might look a bit funny--the lexer will happily use a close
brace to close a context open by a virtual brace. This is not a problem
since the parser will make sure the braces are appropriately matched.

Start a new layout context. This is one of two ways to get out of the
layout state (the other is openBrace). There are
two possibilities:

The current token is to the right of the current layout context (or we're
in a no layout context).

The current token is to the left of or in the same column as the current
context.

In the first case everything is fine and we enter a new layout context at
the column of the current token. In the second case we have an empty layout
block so we enter the empty_layout state. In both
cases we return a virtual open brace without consuming any input.

Entering a new state when we know we want to generate a virtual {} may
seem a bit roundabout. The thing is that we can only generate one token at
a time, so the way to generate two tokens is to generate the first one and
then enter a state in which the only thing you can do is generate the
second one.