%
% $Header: /home/cvs/root/haskell-report/report/layout.verb,v 1.1 2001/03/28 14:13:42 simonpj Exp $
%
% partain:
% in a separate file, because it is included twice (for now);
%  in intro.verb and syntax.verb

% First para added from both sections -- KH
% (was other parts for rest in the first sentence of syntax.verb)

In the syntax given in the rest of the report, {\em layout 
lists} are always preceded by the keyword @where@, @let@, @do@,
or @of@, and are
enclosed within curly braces (@{ }@) with the individual declarations
separated by semicolons (@;@).  Layout lists usually contain
declarations, but @do@ and @case@ introduce lists of other sorts.
For example, the syntax of a @let@
expression is:
\[
@let {@\ decl_1\ @;@\ decl_2\ @;@\ ...\ @;@\ decl_n\ @} in@\ exp
\]

\Haskell{} permits the omission of the braces and semicolons by
using {\em layout} to convey the same information.  This allows both
layout-sensitive and -insensitive styles of coding, which
can be freely mixed within one program.  Because layout is
not required, \Haskell{} programs can be straightforwardly
produced by other programs.
% without worrying about deeply nested layout difficulties.

The layout (or ``off-side'') rule\index{off-side rule} takes effect
whenever the open brace is omitted after the keyword @where@, @let@,
@do@, or
@of@.  When this happens, the indentation of the next lexeme (whether
or not on a new line) is remembered and the omitted open brace is
inserted (the whitespace preceding the lexeme may include comments).
For each subsequent line, if it contains only whitespace or is
indented more, then the previous item is continued (nothing is
inserted); if it is indented the same amount, then a new item begins
(a semicolon is inserted); and if it is indented less, then the
layout list ends (a close brace is inserted).  A close brace is
also inserted whenever the syntactic category containing the
layout list ends; that is, if an illegal lexeme is encountered at
a point where a close brace would be legal, a close brace is inserted.
The layout rule matches only those open braces that it has
inserted; an explicit open brace must be matched by
an explicit close brace.  Within these explicit open braces,
{\em no} layout processing is performed for constructs outside the
braces, even if a line is 
indented to the left of an earlier implicit open brace.

Given these rules, a single newline may actually terminate several
layout lists.  Also, these rules permit:
\bprog
@
f x = let a = 1; b = 2 
          g y = exp2
       in exp1
@
\eprog
making @a@, @b@ and @g@ all part of the same layout
list.

To facilitate the use of layout at the top level of a module
(an implementation may allow several modules may reside in one file),
the keyword 
@module@ and the end-of-file token are assumed to occur in column
0 (whereas normally the first column is 1).  Otherwise, all
top-level declarations would have to be indented.

Section~\ref{layout} gives a more precise definition of the layout rules.

