ghc/interpreter/iface.g

   1 /****************************************************************
   2  * Grammar for interface files
   3  ****************************************************************/
   4
   5 This document purports to describe the syntax (and semantics?) of
   6 interface files generated by GHC for use by Hugs.
   7
   8
   9 /****************************************************************
  10  * ToDo:
  11  ****************************************************************/
  12
  13 o GHC currently generates "Functor( :Functor :Functor map )" in export lists.
  14   This is no longer legal and is very confusing besides - but what
  15   will GHC generate instead?
  16
  17
  18 /****************************************************************
  19  * Closures generated by GHC
  20  ****************************************************************/
  21
  22 GHC generates a closure for the following objects (if exported):
  23
  24 o variables
  25 o instance decls
  26 o methods selectors and superclass selectors
  27 o selector functions (from record syntax)
  28 o data constructors
  29
  30 If an object foo (respectively Foo) is declared in a module Bar, then
  31 the closure is called Bar_foo_closure (respectively Bar_Foo_closure).
  32
  33 Whether the object is static or not is not reflected in the name.  The
  34 type or arity of the object is not reflected in the name.  The name is
  35 just Bar_foo_closure.
  36
  37 Modifications to the above:
  38
  39 1) Depending on the architecture, it might be necessary to add a
  40    leading underscore to the name.
  41
  42 2) We also have to apply the infamous Z-encoding:
  43
  44    Code from somewhere inside GHC (circa 1994)
  45    * Z-escapes:
  46        "std"++xs -> "Zstd"++xs
  47        char_to_c 'Z'  = "ZZ"
  48        char_to_c '&'  = "Za"
  49        char_to_c '|'  = "Zb"
  50        char_to_c ':'  = "Zc"
  51        char_to_c '/'  = "Zd"
  52        char_to_c '='  = "Ze"
  53        char_to_c '>'  = "Zg"
  54        char_to_c '#'  = "Zh"
  55        char_to_c '<'  = "Zl"
  56        char_to_c '-'  = "Zm"
  57        char_to_c '!'  = "Zn"
  58        char_to_c '.'  = "Zo"
  59        char_to_c '+'  = "Zp"
  60        char_to_c '\'' = "Zq"
  61        char_to_c '*'  = "Zt"
  62        char_to_c '_'  = "Zu"
  63        char_to_c c    = "Z" ++ show (ord c)
  64
  65    (There's a commented out piece of code in rts/Printer.c which
  66     implements this.)
  67
  68
  69 /****************************************************************
  70  * Lexical syntax
  71  ****************************************************************/
  72
  73 The lexical syntax is exactly the same as for Haskell with the
  74 following additions:
  75
  76 Keywords
  77 ~~~~~~~~
  78
  79 We add: __export __interface __requires
  80
  81
  82 Pragmas
  83 ~~~~~~~
  84
  85 GHC will use pragmas of the form: {-## ##-}.
  86
  87 These are always ignored by Hugs and may be ignored by GHC.
  88
  89 GHC will be able to use lazy parsing for these - just as it
  90  currently does for unfoldings and the like.
  91
  92
  93 Compiler generated names
  94 ~~~~~~~~~~~~~~~~~~~~~~~~
  95
  96 Are of the form _letter(letter|digit|symbol)*.
  97
  98 It's important that they can always be generated by putting "_l"
  99 in front of a valid Haskell varid, varop, conid or conop.
 100
 101 It's also important that valid Haskell patterns such as _:_
 102 should not be valid compiler generated names.
 103
 104 The letter indicates something about the kind of object it is
 105 but all that Hugs needs to do is separate conid/ops from varid/ops
 106 - which it does depending on whether the letter is uppercase.
 107
 108
 109 /****************************************************************
 110  * Header
 111  ****************************************************************/
 112
 113 iface         : '__interface' ifaceName NUMLIT version 'where' Body
 114
 115 Body          : '__requires' STRINGLIT ';'
 116                 { importDecl         ';' }
 117                 { instanceImportDecl ';' }
 118                 { exportDecl         ';' }
 119                 { fixityDecl         ';' }
 120                 { classDecl          ';' }
 121                 { instanceDecl       ';' }
 122                 { typeDecl           ';' }
 123                 { valueDecl          ';' }
 124
 125 version       : NUMLIT
 126
 127 /****************************************************************
 128  * Import-export stuff
 129  *
 130  * I believe the meaning of 'import' is "qualified import" - but
 131  * I'm not sure.  - ADR
 132  ****************************************************************/
 133
 134 importDecl         : 'import' CONID NUMLIT
 135 instanceImportDecl : 'instance' 'import' CONID NUMLIT
 136 exportDecl         : '__export' CONID  { Entity }
 137
 138 Entity        : EntityOcc
 139               | EntityOcc StuffInside
 140               | EntityOcc '|' StuffInside
 141
 142 EntityOcc     : Var
 143               | Data
 144               | '->'
 145               | '(' '->' ')'
 146
 147 StuffInside   : '{' ValOcc { ValOcc } '}'
 148
 149 ValOcc        : Var
 150               | Data
 151
 152 /****************************************************************
 153  * Fixities
 154  ****************************************************************/
 155
 156 fixityDecl    : 'infixl' optdigit op
 157               | 'infixr' optdigit op
 158               | 'infix'  optdigit op
 159
 160 /****************************************************************
 161  * Type declarations
 162  *
 163  * o data decls use "Data" on lhs and rhs to allow this decl:
 164  *
 165  *     data () = ()
 166  *
 167  * o data declarations don't have the usual Haskell syntax:
 168  *   o they don't have strictness annotations
 169  *   o they are given an explicit signature instead of a list of
 170  *     argument types
 171  *   o field selectors are given an explicit signature
 172  *
 173  *   [Simon PJ asked me to look again at how much work it would take to
 174  *   handle the standard syntax.  The answer is:
 175  *   o It takes an awful lot of code to process the standard syntax.
 176  *   o I can hardly reuse any of the existing code because it is too
 177  *     tightly interwoven with other parts of static analysis.
 178  *   o The rules for processing data decls are very intricate
 179  *     (and are worse since existentials and local polymorphism were
 180  *     added).  Implementing a complicated thing twice (once in
 181  *     GHC and once in Hugs) is bad; implementing it a third time
 182  *     is Just Plain Wrong.
 183  *   ]
 184  *
 185  *   Data decls look like this:
 186  *
 187  *     data List a = Nil         :: forall [a] => List a
 188  *                 | Cons{hd,tl} :: forall [a] => a -> List a -> List a
 189  *       where
 190  *        hd :: forall [a] => List a -> a
 191  *        tl :: forall [a] => List a -> List a
 192  *
 193  *   o The tyvars on the lhs serve only to help infer the kind of List
 194  *   o The type of each data constructor and selector is written
 195  *     explicitly.
 196  *   o A small amount of work is required to figure out which
 197  *     variables are existentially quantified.
 198  *   o GHC will require an inlining pragma to recover strictness
 199  *     annotations.
 200  ****************************************************************/
 201
 202 typeDecl      : NUMLIT 'type' TCName {TVBndr} '=' Type
 203               | NUMLIT 'data' Data {TVBndr} ['=' Constrs ['where' Sels]]
 204               | NUMLIT 'newtype' TCName {TVBndr} [ '=' Data AType ]
 205
 206 Constrs       : Constr {'|' Constr}
 207 Constr        : Data [Fields] '::' Type
 208 Fields        : '{' VarName {',' VarName} '}'
 209
 210 Sels          : Sel {';' Sel}
 211 Sel           : VarName '::' ['!'] Type
 212
 213 /****************************************************************
 214  * Classes and instances
 215  *
 216  * Question: should the method signature include the class
 217  * constraint?  That is, should we write the Eq decl like this:
 218  *
 219  *   class Eq a where { (==) :: a -> a -> Bool } -- like Haskell
 220  *
 221  * or like this
 222  *
 223  *   class Eq a where { (==) :: Eq a => a -> a -> Bool }
 224  *
 225  * There's not much to choose between them but the second version
 226  * is more consistent with what we're doing with data constructors.
 227  ****************************************************************/
 228
 229 classDecl     : NUMLIT 'class' [ Context '=>' ] TCName {TVBndr} 'where' CSigs
 230 instanceDecl  : 'instance' [Quant] Class '=' Var
 231
 232 CSigs         : '{' CSig { ';' CSigs } '}'
 233 CSig          : VarName ['='] '::' Type
 234
 235 /****************************************************************
 236  * Types
 237  ****************************************************************/
 238
 239 Type          : Quant Type
 240               | BType '->' Type
 241               | BType
 242
 243 Context       : '(' Class { ',' Class } ')'
 244
 245 Class         : QTCName { AType }
 246
 247 BType         : AType { AType }
 248
 249 AType         : QTCName
 250               | TVName
 251               | '(' ')'                             // unit
 252               | '(' Type ')'                        // parens
 253               | '(' Type ',' Type { ',' Type } ')'  // tuple
 254               | '[' Type ']'                        // list
 255               | '{' QTCName { AType } '}'           // dictionary
 256
 257
 258 Quant         : 'forall' {TVBndr} [Context] '=>'
 259
 260 TVBndr        : TVName [ '::' AKind ]
 261
 262 Kind          : { AKind -> } AKind
 263 AKind         : VAROP                               // really '*'
 264               | '(' Kind ')'
 265
 266 /****************************************************************
 267  * Values
 268  ****************************************************************/
 269
 270 valueDecl     : NUMLIT Var '::' Type
 271
 272 /****************************************************************
 273  * Atoms
 274  ****************************************************************/
 275
 276 VarName       : Var
 277 TVName        : VARID
 278
 279 Var           : VARID
 280               | VAROP
 281               | '!'
 282               | '.'
 283               | '-'
 284
 285 Data          : CONID
 286               | CONOP
 287               | '(' ')'
 288               | '[' ']'
 289
 290 TCName        : CONID
 291               | CONOP
 292               | '(' '->' ')'
 293               | '[' ']'
 294
 295 QTCName       : TCName
 296               | QCONID
 297               | QCONOP
 298
 299 ifaceName     : CONID
 300
 301 /****************************************************************
 302  * End
 303  ****************************************************************/
 304