[project @ 1996-01-08 20:28:12 by partain]
[ghc.git] / ghc / docs / Prefix_Form
1                         Haskell Prefix Form
2                         ===================
3
4 This defines the interface between the Haskell lexer/parser "hsp"
5 (written in lex/yacc/C) and the Haskell compiler proper, "hsc"
6 (written in Haskell).
7
8 White space in the form of spaces, tabs and newlines may occur between
9 prefix items (I wouldn't recommend it [WDP]).  A literal tab
10 terminates a string constant (and by extension also an integer
11 constant, character constant, identifier or infix operator).
12
13 There is a general list form, where L indicates a Cons node and N
14 indicates Nil.  Elements in a list may be of arbitrary type.
15
16 KH, 22/08/91:   Changed for Haskell 1.1+ -- this is where Haskell and LML
17                 finally part company...
18
19 JH, 09/07/92:   {0,5,6,I,O,u,v,w} Used in Data Parallel Haskell variant 
20                 (Jonathan Hill, QMW)
21
22 WDP, 02/04/93:  Added full-blown pragmas.
23 WDP, 15/08/93:  Added even more full-blown pragmas.
24
25 `Tag' namespace already used:
26
27 #$%()+,-.012356789:=>@ABCDEGILMNOPQRSTUWXZ_abcdefghijklmnopstuvwxyz~
28
29                         Meta-Syntactic Items
30                         --------------------
31
32 Lists (l)
33 ---------
34
35 L  el  l                List constructor                el : l
36 N                       Null List                       []
37
38
39 Strings (s)
40 -----------
41
42 #chars<TAB>             String of characters before <TAB>
43
44
45
46
47                         Syntactic Items
48                         ---------------
49
50 Expressions or Patterns (e or p)
51 --------------------------------
52
53 M  L s s b [op] [ix] [ei]
54                         Haskell module:
55                         (name, file, binding, fixities, imports, exports)
56
57 4 s                     Integer Constant                0, 1, ...
58 H s                     Unboxed Integer constant        0#, 1#, ... /* WDP */
59 F s                     Floating Point Constant         0.1, 0.2e-3, ...
60 J s                     Unboxed Double Constant         0.1##, 0.2e-3##, ... /* WDP */
61 K s                     Unboxed Float Constant          0.1#, 0.2e-3#, ... /* WDP */
62 C s                     Character Constant              '...'
63 P s                     Unboxed character constant      ???????? /* WDP */
64 S s                     String Constant                 "..."
65 V s                     String# Constant                "..."# /* WDP */
66 Y s                     "Literal C" Constant            ``printf'' /* WDP */
67 I s                     "no rep" Integer (unfoldings)
68 R s s                   "no rep" Rational (numerator, denominator)
69 s s                     "no rep" String constant (unfoldings)
70
71 i  id                   Identifiers
72 C  literal              Literal constant
73
74 a  e1  e2               Function application            (e1 e2)
75 @  e1  id  e2           Infix Application               e1 `op` e2
76 (  e   id               Left section                    (e op)
77 )  id  e                Right Section                   (op e)
78
79 l  L   [p]   e          Lambda Expressions              \ p1 ... pn -> e
80 c  e   [pb]             Case Expression                 case e of pb1 ... pbn
81 b  e1 e2 e3             If expression                   if e1 then e2 else e3
82 E  b   e                Let Expression                  let b in e
83
84 :  [e]                  Explicit List                   [ e1, ..., en ]
85 Z  e   [q]              List Comprehension              [ e | q ]
86 .  e1  [e2]  [e3]       Enumeration (e2/e3 may be [])   [e1,e2..e3]
87
88 ,  [e]                  Explicit Tuple                  ( e1, ..., en )
89
90 R  e   t                Type Constraint                 e :: t
91
92 -  e                    Negation                        - e
93
94 j  id s [e]             C Call/Asm                      (ccall/asm id/str e1 ... en)
95                         s == "n" --> ccall, non-ptrs only
96                         s == "p" --> ccall, ptrs allowed
97                         s == "N" --> casm, non-ptrs only
98                         s == "P" --> casm, ptrs allowed
99 k  s  e                 Set Cost Centre                 (scc s e)
100
101 s  id  p                As Pattern                      id @ p
102 ~  p                    Irrefutable Pattern             ~ p
103 +  p   e                Plus Pattern                    n + k
104                         /*WDP: why a "p" on the plus pat? (KH: historical reasons) */
105 _                       Wildcard Pattern                _
106
107
108
109 Qualifiers (q)
110 --------------
111
112 G  p  e                 Generator                       p <- e
113 g  e                    Guard                           e
114
115 Bindings (b)
116 ------------
117
118 t  L C  [id] t [d] iprag DataType Binding               data C => t = d1 | ... | dn 
119                                                                 deriving (id1, ..., idm)
120 n  L t1 t2 iprag        Type Synonym                    type t1 = t2
121 p  L [pb]               Pattern Binding                 pb1 ; ... ; pbn
122 f  L [pb]               Function Binding                pb1 ; ... ; pbn
123 A  b1   b2              Multiple Definitions            b1 ; b2
124 $  L C t  b iprag       Class                           class C => t [where b]
125 %  L C id t b iprag     Instance                        instance C => id t [where b]
126 D  L [ty]               Default                         default (ty1, ..., tyn)
127
128 St L [id] t iprag       Type Signature                  id1, ...., idn :: t
129 Ss L id [t]             Pragma: value specialis'ns      {-# SPECIALISE id :: t1, ... tn #-}
130 SS L id t               Pragma: instance specialis'n    {-# SPECIALISE instance id t #-}
131 Si L id [id]            Pragma: inline -- id [howto]    {-# INLINE id [id]{0,1} #-}
132 Su L id                 Pragma: magic unfolding         {-# MAGIC_UNFOLDING id #-}
133 Sa L id                 Pragma: abstract synonym        {-# ABSTRACT id #-}
134
135 7  L id   [ei] [rn]     Import module (Interface only)  import id (eis) renaming rn
136 B                       null binding
137
138
139 Fixity declarations (op)
140 --------------
141 /* WDP: most suspicious how these don't appear in interfaces */
142 /* WDP: need line numbers? */
143
144    s1   s2   s3         s1 is the operator name
145                         s2 is either "infix", "infixl" or "infixr"
146                         s3 is the precedence
147
148 Types (t)
149 ---------
150
151 T  id   [t]             Type Constructor                id t1 ... tn
152 :  t                    Explicit List Type              [t]
153 ,  [t]                  Explicit Tuple Type             (t1, ..., tn)
154 >  t1   t2              Explicit Function Type          t1 -> t2
155 y  id                   Type Variable                   id
156 3  C    t               Type Context                    C => t
157
158 2A id t                 "UniDict": class, type  (core unfoldings only)
159 2B id                   "UniTyVarTemplate"
160 2C [id] t               "UniForall" tv1 ... tvN => type
161
162 2D                      Nothing (Maybe UniType)
163 2E t                    Just t  (ditto)
164
165 Contexts (C)
166 ------------
167
168    [t]                  Haskell context: t1, ..., tn
169
170
171 Data Types (d)
172 --------------
173
174 1  L id [t]             Data constructor                id st1 ... stn
175
176
177 Pattern Bindings (pb)
178 ---------------------
179
180 W  L id p  [ge] b       Single grhs                     p | g1 = e1 ... where b
181                         (L,id) = (Line,Function)
182
183
184 Guarded Expressions (ge)
185 ------------------------
186
187    g  e         g | e   (unguarded comes in with an
188                         unsavoury (Var "_otherwise") `guard')
189
190
191 Identifiers (id)
192 ----------------
193
194    s                    An identifier is just a string
195
196
197 Import declarations (ix)
198 ------------------------
199
200 e  L s id [ei] [rn] b   Line, File Name, Module name, imported entities,
201                         renamings, interface body
202 h  L s id [ei] [rn] b   Hiding clause, as above...
203
204
205 Renamings (rn)
206 --------------
207
208    id id                From name, to name
209
210
211 Exported/Imported Identifers (ei)
212 ---------------------------------
213
214 x  id                   ExImport Variable
215 X  id                   ExImport Constructor/Type/Class
216 z  id                   ExImport Class/Type plus all ops/cons
217 8  id [id]              ExImport Type(C1,..Cn)
218 9  id [id]              ExImport Class(o1,..on)
219 m  id                   Export Module
220
221
222 Interface pragmas (iprag)
223 -------------------------
224
225         User pragmas come in as "signatures"; see Bindings.
226
227 PN                      Null/empty pragma
228
229 Pd  [d]                 Data pragma: otherwise-hidden data constructors
230 Pt                      Type pragma: synonym is *abstract*
231 Pc  [gprag]             Class pragma: one gprag per superclass
232 Po  gprag gprag         Class op pragma: gprags for dsel & defm
233   OUT: Pv  gprag [2prag]        Value pragma: gprag + specialisations
234 Pis id gprag            Instance pragma (simple): id is module name, gprag for dfun
235 Pic id gprag [1prag]    Ditto (constant methods): also gprags for classops
236 PiS id gprag [3prag]    Ditto (specialised): also (type, instance-prag) pairs
237
238 Pg  Aprag uprag Sprag Uprag
239                         General ("gprag"): arity, update, strictness, unfolding
240
241 PA  id                  Arity ("Aprag"): arity
242 Pu  id                  Update ("uprag"): update spec
243 PS  id gprag            Strictness ("Sprag"): strictness spec, gprag for worker
244 PM  id id               Magic unfolding ("Uprag"): var, magic-name string
245 PU  id core             Unfolding ("Uprag"): "guidance", corexpr-unfolding
246
247 Px                      Unfold always (these are "guidance" ones...)
248 Py  id id               Unfold if applied to "m" ty args, "n" val args
249 Pz  id id               Unfold if applied to "m" ty args, & cons in marked val positions
250                         (e.g., "CXXCXX" ==> in 1st & 4th arg positions)
251
252 P1  id gprag            ("1prag"): (name, gen-pragma) pair
253 P2  t  gprag            ("2prag"): (type, gen-pragma) pair
254 P3  t  gprag [iprag]    ("3prag"): (type, [(gen-pragma, instance-pragma)]) pair
255
256
257 Core syntax [in iprags] (core)
258 ------------------------------
259
260 Fa
261 Fb
262 <etc -- lots of this stuff>
263
264 Used in Data Parallel Haskell variant (Jonathan Hill, QMW)
265 ----------------------------------------------------------
266
267     ** Expressions **
268
269 5  e   [parqual]        Parallel ZF expression  << e | [parquals] >>
270 6  [e]                  Pod Literal             << e1,...,ek>>
271 O  [e] e                Processor (|e1,...,ek;e|)
272
273     ** Types **
274
275 u  [t] t                Explicit Processor Type         (|t1,..tn;t|)
276 v  [t]                  Explicit Pod Type               <<t>>
277
278     ** Parallel Qualifiers **
279
280 0 e e                   Drawn From Generator    exp <<- exp
281 w e e                   Indexed From Generator  exp <<= exp
282 I e                     Guard
283
284
285                              Other Items
286                              -----------
287
288 Line Numbers (L)
289 ----------------
290
291    s                    Haskell line number
292
293
294 Kevin Hammond @ 22nd. August 1991