update READMEs
[haskell-report.git] / report / layout.verb
1 %
2 % $Header: /home/cvs/root/haskell-report/report/layout.verb,v 1.1 2001/03/28 14:13:42 simonpj Exp $
3 %
4 % partain:
5 % in a separate file, because it is included twice (for now);
6 %  in intro.verb and syntax.verb
7
8 % First para added from both sections -- KH
9 % (was other parts for rest in the first sentence of syntax.verb)
10
11 In the syntax given in the rest of the report, {\em layout 
12 lists} are always preceded by the keyword @where@, @let@, @do@,
13 or @of@, and are
14 enclosed within curly braces (@{ }@) with the individual declarations
15 separated by semicolons (@;@).  Layout lists usually contain
16 declarations, but @do@ and @case@ introduce lists of other sorts.
17 For example, the syntax of a @let@
18 expression is:
19 \[
20 @let {@\ decl_1\ @;@\ decl_2\ @;@\ ...\ @;@\ decl_n\ @} in@\ exp
21 \]
22
23 \Haskell{} permits the omission of the braces and semicolons by
24 using {\em layout} to convey the same information.  This allows both
25 layout-sensitive and -insensitive styles of coding, which
26 can be freely mixed within one program.  Because layout is
27 not required, \Haskell{} programs can be straightforwardly
28 produced by other programs.
29 % without worrying about deeply nested layout difficulties.
30
31 The layout (or ``off-side'') rule\index{off-side rule} takes effect
32 whenever the open brace is omitted after the keyword @where@, @let@,
33 @do@, or
34 @of@.  When this happens, the indentation of the next lexeme (whether
35 or not on a new line) is remembered and the omitted open brace is
36 inserted (the whitespace preceding the lexeme may include comments).
37 For each subsequent line, if it contains only whitespace or is
38 indented more, then the previous item is continued (nothing is
39 inserted); if it is indented the same amount, then a new item begins
40 (a semicolon is inserted); and if it is indented less, then the
41 layout list ends (a close brace is inserted).  A close brace is
42 also inserted whenever the syntactic category containing the
43 layout list ends; that is, if an illegal lexeme is encountered at
44 a point where a close brace would be legal, a close brace is inserted.
45 The layout rule matches only those open braces that it has
46 inserted; an explicit open brace must be matched by
47 an explicit close brace.  Within these explicit open braces,
48 {\em no} layout processing is performed for constructs outside the
49 braces, even if a line is 
50 indented to the left of an earlier implicit open brace.
51
52 Given these rules, a single newline may actually terminate several
53 layout lists.  Also, these rules permit:
54 \bprog
55 @
56 f x = let a = 1; b = 2 
57           g y = exp2
58        in exp1
59 @
60 \eprog
61 making @a@, @b@ and @g@ all part of the same layout
62 list.
63
64 To facilitate the use of layout at the top level of a module
65 (an implementation may allow several modules may reside in one file),
66 the keyword 
67 @module@ and the end-of-file token are assumed to occur in column
68 0 (whereas normally the first column is 1).  Otherwise, all
69 top-level declarations would have to be indented.
70
71 Section~\ref{layout} gives a more precise definition of the layout rules.
72