Ticket #5469: 0001-Add-more-documentation.patch

File 0001-Add-more-documentation.patch, 21.0 KB (added by reinerp, 3 years ago)
  • Language/Haskell/TH/Syntax.hs

    From 9f952f35a773a477d924f0f6694224474b9e7062 Mon Sep 17 00:00:00 2001
    From: Reiner Pope <[email protected]>
    Date: Sat, 9 Jun 2012 15:32:30 +1000
    Subject: [PATCH 1/4] Add more documentation.
    
    ---
     Language/Haskell/TH/Syntax.hs |  410 +++++++++++++++++++++++++++++++++--------
     1 files changed, 330 insertions(+), 80 deletions(-)
    
    diff --git a/Language/Haskell/TH/Syntax.hs b/Language/Haskell/TH/Syntax.hs
    index c18d801..e7a72a8 100644
    a b counter = unsafePerformIO (newIORef 0) 
    147147 
    148148newtype Q a = Q { unQ :: forall m. Quasi m => m a } 
    149149 
     150-- \"Runs\" the 'Q' monad. Normal users of Template Haskell 
     151-- should not need this function, as the splice brackets @$( ... )@ 
     152-- are the usual way of running a 'Q' computation. 
     153-- 
     154-- This function is primarily used in GHC internals, and for debugging 
     155-- splices by running them in 'IO'.  
     156-- 
     157-- Note that many functions in 'Q', such as 'reify' and other compiler 
     158-- queries, are not supported when running 'Q' in 'IO'; these operations 
     159-- simply fail at runtime. Indeed, the only operations guaranteed to succeed 
     160-- are 'newName', 'runIO', 'reportError' and 'reportWarning'. 
    150161runQ :: Quasi m => Q a -> m a 
    151162runQ (Q m) = m 
    152163 
    instance Applicative Q where 
    165176 
    166177---------------------------------------------------- 
    167178-- Packaged versions for the programmer, hiding the Quasi-ness 
     179 
     180{- |  
     181Generate a fresh name, which cannot be captured.  
     182 
     183For example, this: 
     184 
     185@f = $(do 
     186  nm1 <- newName \"x\" 
     187  let nm2 = 'mkName' \"x\" 
     188  return ('LamE' ['VarP' nm1] (LamE [VarP nm2] ('VarE' nm1))) 
     189 )@ 
     190 
     191will produce the splice 
     192 
     193>f = \x0 -> \x -> x0 
     194 
     195In particular, the occurrence @VarE nm1@ refers to the binding @VarP nm1@, 
     196and is not captured by the binding @VarP nm2@. 
     197 
     198Although names generated by @newName@ cannot /be captured/, they can 
     199/capture/ other names. For example, this: 
     200 
     201>g = $(do 
     202>  nm1 <- newName "x" 
     203>  let nm2 = mkName "x" 
     204>  return (LamE [VarP nm2] (LamE [VarP nm1] (VarE nm2))) 
     205> ) 
     206 
     207will produce the splice 
     208 
     209>g = \x -> \x0 -> x0 
     210 
     211since the occurrence @VarE nm2@ is captured by the innermost binding 
     212of @x@, namely @VarP nm1@. 
     213-} 
    168214newName :: String -> Q Name 
    169215newName s = Q (qNewName s) 
    170216 
     217-- | Report an error (True) or warning (False),  
     218-- but carry on; use 'fail' to stop. 
    171219report  :: Bool -> String -> Q () 
    172220report b s = Q (qReport b s) 
    173221 
    174 recover :: Q a -- ^ recover with this one 
    175         -> Q a -- ^ failing action 
     222-- | Recover from errors raised by 'reportError' or 'fail'. 
     223recover :: Q a -- ^ handler to invoke on failure 
     224        -> Q a -- ^ computation to run 
    176225        -> Q a 
    177226recover (Q r) (Q m) = Q (qRecover r m) 
    178227 
    recover (Q r) (Q m) = Q (qRecover r m) 
    181230lookupName :: Bool -> String -> Q (Maybe Name) 
    182231lookupName ns s = Q (qLookupName ns s) 
    183232 
    184 lookupTypeName, lookupValueName :: String -> Q (Maybe Name) 
     233-- | Look up the given name in the (type namespace of the) current splice's scope. See "Language.Haskell.TH.Syntax#namelookup" for more details. 
     234lookupTypeName :: String -> Q (Maybe Name) 
    185235lookupTypeName  s = Q (qLookupName True s) 
     236 
     237-- | Look up the given name in the (value namespace of the) current splice's scope. See "Language.Haskell.TH.Syntax#namelookup" for more details. 
     238lookupValueName :: String -> Q (Maybe Name) 
    186239lookupValueName s = Q (qLookupName False s) 
    187240 
    188 -- | 'reify' looks up information about the 'Name' 
     241{- 
     242Note [Name lookup] 
     243~~~~~~~~~~~~~~~~~~ 
     244-} 
     245{- $namelookup #namelookup# 
     246The functions 'lookupTypeName' and 'lookupValueName' provide 
     247a way to query the current splice's context for what names 
     248are in scope. The function 'lookupTypeName' queries the type 
     249namespace, whereas 'lookupValueName' queries the value namespace, 
     250but the functions are otherwise identical. 
     251 
     252A call @lookupValueName s@ will check if there is a value 
     253with name @s@ in scope at the current splice's location. If 
     254there is, the @Name@ of this value is returned; 
     255if not, then @Nothing@ is returned. 
     256 
     257The returned name cannot be \"captured\".  
     258For example: 
     259 
     260> f = "global" 
     261> g = $( do 
     262>          Just nm <- lookupValueName "f" 
     263>          [| let f = "local" in $( varE nm ) |] 
     264 
     265In this case, @g = \"global\"@; the call to @lookupValueName@ 
     266returned the global @f@, and this name was /not/ captured by 
     267the local definition of @f@. 
     268 
     269The lookup is performed in the context of the /top-level/ splice 
     270being run. For example: 
     271 
     272> f = "global" 
     273> g = $( [| let f = "local" in  
     274>            $(do 
     275>                Just nm <- lookupValueName "f" 
     276>                varE nm 
     277>             ) |] ) 
     278 
     279Again in this example, @g = \"global\"@, because the call to 
     280@lookupValueName@ queries the context of the outer-most @$(...)@. 
     281 
     282Operators should be queried without any surrounding parentheses, like so: 
     283 
     284> lookupValueName "+" 
     285 
     286Qualified names are also supported, like so: 
     287 
     288> lookupValueName "Prelude.+" 
     289> lookupValueName "Prelude.map" 
     290 
     291-} 
     292 
     293 
     294{- | 'reify' looks up information about the 'Name'. 
     295 
     296It is sometimes useful to construct the argument name using 'lookupTypeName' or 'lookupValueName' 
     297to ensure that we are reifying from the right namespace. For instance, in this context: 
     298 
     299> data D = D 
     300 
     301which @D@ does @reify (mkName \"D\")@ return information about? (Answer: @D@-the-type, but don't rely on it.) 
     302To ensure we get information about @D@-the-value, use 'lookupValueName': 
     303 
     304> do 
     305>   Just nm <- lookupValueName "D" 
     306>   reify nm 
     307 
     308and to get information about @D@-the-type, use 'lookupTypeName'. 
     309-} 
    189310reify :: Name -> Q Info 
    190311reify v = Q (qReify v) 
    191312 
    192 -- | 'classInstances' looks up instaces of a class 
    193 reifyInstances :: Name -> [Type] -> Q [Dec] 
     313{- | @reifyInstances nm tys@ returns a list of visible instances of @nm tys@. That is,  
     314if @nm@ is the name of a type class, then all instances of this class at the types @tys@ 
     315are returned. Alternatively, if @nm@ is the name of a data family or type family, 
     316all instances of this family at the types @tys@ are returned. 
     317-} 
     318reifyInstances :: Name -> [Type] -> Q [InstanceDec] 
    194319reifyInstances cls tys = Q (qReifyInstances cls tys) 
    195320 
     321-- | Is the list of instances returned by 'reifyInstances' nonempty? 
    196322isInstance :: Name -> [Type] -> Q Bool 
    197323isInstance nm tys = do { decs <- reifyInstances nm tys 
    198324                       ; return (not (null decs)) } 
    199325 
    200 -- | 'location' gives you the 'Location' at which this 
    201 -- computation is spliced. 
     326-- | The location at which this computation is spliced. 
    202327location :: Q Loc 
    203328location = Q qLocation 
    204329 
    occString (OccName occ) = occ 
    363488----------------------------------------------------- 
    364489--               Names 
    365490----------------------------------------------------- 
    366  
    367 -- | 
     491--  
    368492-- For "global" names ('NameG') we need a totally unique name, 
    369493-- so we must include the name-space of the thing 
    370494-- 
    occString (OccName occ) = occ 
    388512-- The 'map' will be a NameG, and 'x' wil be a NameL 
    389513-- 
    390514-- These Names should never appear in a binding position in a TH syntax tree 
     515 
     516{- $namecapture #namecapture# 
     517Much of 'Name' API is concerned with the problem of /name capture/, which 
     518can be seen in the following example. 
     519 
     520> f expr = [| let x = 0 in $expr |] 
     521> ... 
     522> g x = $( f [| x |] ) 
     523> h y = $( f [| y |] ) 
     524 
     525A naive desugaring of this would yield: 
     526 
     527> g x = let x = 0 in x 
     528> h y = let x = 0 in y 
     529 
     530All of a sudden, @g@ and @h@ have different meanings! In this case, 
     531we say that the @x@ in the RHS of @g@ has been /captured/ 
     532by the binding of @x@ in @f@. 
     533 
     534What we actually want is for the @x@ in @f@ to be distinct from the 
     535@x@ in @g@, so we get the following desugaring: 
     536 
     537> g x = let x' = 0 in x 
     538> h y = let x' = 0 in y 
     539 
     540which avoids name capture as desired.  
     541 
     542In the general case, we say that a @Name@ can be captured if 
     543the thing it refers to can be changed by adding new declarations. 
     544-} 
     545 
     546{- | 
     547An abstract type representing names in the syntax tree. 
     548 
     549'Name's can be constructed in several ways, which come with different 
     550name-capture guarantees (see "Language.Haskell.TH.Syntax#namecapture" for 
     551an explanation of name capture): 
     552 
     553  * the built-in syntax @'f@ and @''T@ can be used to construct names,  
     554    The expression @'f@ gives a @Name@ which refers to the value @f@  
     555    currently in scope, and @''T@ gives a @Name@ which refers to the 
     556    type @T@ currently in scope. These names can never be captured. 
     557     
     558  * 'lookupValueName' and 'lookupTypeName' are similar to @'f@ and  
     559     @''T@ respectively, but the @Name@s are looked up at the point 
     560     where the current splice is being run. These names can never be 
     561     captured. 
     562 
     563  * 'newName' monadically generates a new name, which can never 
     564     be captured. 
     565      
     566  * 'mkName' generates a capturable name. 
     567 
     568Names constructed using @newName@ and @mkName@ may be used in bindings 
     569(such as @let x = ...@ or @\x -> ...@), but names constructed using 
     570@lookupValueName@, @lookupTypeName@, @'f@, @''T@ may not. 
     571-} 
    391572data Name = Name OccName NameFlavour deriving (Typeable, Data) 
    392573 
    393574data NameFlavour 
    data NameSpace = VarName -- ^ Variables 
    452633 
    453634type Uniq = Int 
    454635 
    455 -- | Base, unqualified name. 
     636-- | The name without its module prefix 
    456637nameBase :: Name -> String 
    457638nameBase (Name occ _) = occString occ 
    458639 
     640-- | Module prefix of a name, if it exists 
    459641nameModule :: Name -> Maybe String 
    460642nameModule (Name _ (NameQ m))     = Just (modString m) 
    461643nameModule (Name _ (NameG _ _ m)) = Just (modString m) 
    462644nameModule _                      = Nothing 
    463645 
     646{- |  
     647Generate a capturable name. Occurrences of such names will be 
     648resolved according to the Haskell scoping rules at the occurrence 
     649site. 
     650 
     651For example: 
     652 
     653> f = [| pi + $(varE (mkName "pi")) |] 
     654> ... 
     655> g = let pi = 3 in $f 
     656 
     657In this case, @g@ is desugared to 
     658 
     659> g = Prelude.pi + 3 
     660 
     661Note that @mkName@ may be used with qualified names: 
     662 
     663> mkName "Prelude.pi" 
     664 
     665See also 'Language.Haskell.TH.Lib.dyn' for a useful combinator. The above example could 
     666be rewritten using 'dyn' as 
     667 
     668> f = [| pi + $(dyn "pi") |] 
     669-} 
    464670mkName :: String -> Name 
    465 -- ^ The string can have a '.', thus "Foo.baz", 
     671-- The string can have a '.', thus "Foo.baz", 
    466672-- giving a dynamically-bound qualified name, 
    467673-- in which case we want to generate a NameQ 
    468674-- 
    instance Show Name where 
    589795  show = showName 
    590796 
    591797-- Tuple data and type constructors 
    592 tupleDataName :: Int -> Name    -- ^ Data constructor 
    593 tupleTypeName :: Int -> Name    -- ^ Type constructor 
     798-- | Tuple data constructor 
     799tupleDataName :: Int -> Name 
     800-- | Tuple type constructor 
     801tupleTypeName :: Int -> Name 
    594802 
    595803tupleDataName 0 = mk_tup_name 0 DataName 
    596804tupleDataName 1 = error "tupleDataName 1" 
    mk_tup_name n_commas space 
    608816    tup_mod = mkModName "GHC.Tuple" 
    609817 
    610818-- Unboxed tuple data and type constructors 
    611 unboxedTupleDataName :: Int -> Name    -- ^ Data constructor 
    612 unboxedTupleTypeName :: Int -> Name    -- ^ Type constructor 
     819-- | Unboxed tuple data constructor 
     820unboxedTupleDataName :: Int -> Name 
     821-- | Unboxed tuple type constructor 
     822unboxedTupleTypeName :: Int -> Name 
    613823 
    614824unboxedTupleDataName 0 = error "unboxedTupleDataName 0" 
    615825unboxedTupleDataName 1 = error "unboxedTupleDataName 1" 
    data Loc 
    639849        , loc_start    :: CharPos 
    640850        , loc_end      :: CharPos } 
    641851 
    642 type CharPos = (Int, Int)       -- Line and character position 
     852type CharPos = (Int, Int)       -- ^ Line and character position 
    643853 
    644854 
    645855----------------------------------------------------- 
    type CharPos = (Int, Int) -- Line and character position 
    650860 
    651861-- | Obtained from 'reify' in the 'Q' Monad. 
    652862data Info 
    653   = -- | A class is reified to its declaration  
    654     --   and a list of its instances 
    655     ClassI  
    656         Dec             -- Declaration of the class 
    657         [InstanceDec]   -- The instances of that class 
    658  
     863  =  
     864  -- | A class, with a list of its visible instances 
     865  ClassI  
     866      Dec 
     867      [InstanceDec] 
     868   
     869  -- | A class method 
    659870  | ClassOpI 
    660         Name    -- The class op itself 
    661         Type    -- Type of the class-op (fully polymoprhic) 
    662         Name    -- Name of the parent class 
    663         Fixity 
    664  
     871       Name 
     872       Type 
     873       ParentName 
     874       Fixity 
     875   
     876  -- | A \"plain\" type constructor. \"Fancier\" type constructors are returned using 'PrimTyConI' or 'FamilyI' as appropriate 
    665877  | TyConI  
    666878        Dec 
    667879 
    668   | FamilyI     -- Type/data families 
     880  -- | A type or data family, with a list of its visible instances 
     881  | FamilyI  
    669882        Dec 
    670883        [InstanceDec] 
    671  
    672   | PrimTyConI  -- Ones that can't be expressed with a data type  
    673                 -- decl, such as (->), Int# 
    674         Name  
    675         Int     -- Arity 
    676         Bool    -- False => lifted type; True => unlifted 
    677  
     884   
     885  -- | A \"primitive\" type constructor, which can't be expressed with a 'Dec'. Examples: @(->)@, @Int#@. 
     886  | PrimTyConI  
     887       Name 
     888       Arity 
     889       Unlifted 
     890   
     891  -- | A data constructor 
    678892  | DataConI  
    679         Name    -- The data con itself 
    680         Type    -- Type of the constructor (fully polymorphic) 
    681         Name    -- Name of the parent TyCon 
    682         Fixity 
     893       Name 
     894       Type 
     895       ParentName 
     896       Fixity 
    683897 
     898  {- |  
     899  A \"value\" variable (as opposed to a type variable, see 'TyVarI'). 
     900   
     901  The @Maybe Dec@ field contains @Just@ the declaration which  
     902  defined the variable -- including the RHS of the declaration --  
     903  or else @Nothing@, in the case where the RHS is unavailable to 
     904  the compiler. At present, this value is _always_ @Nothing@: 
     905  returning the RHS has not yet been implemented because of 
     906  lack of interest. 
     907  -} 
    684908  | VarI  
    685         Name    -- The variable itself 
    686         Type  
    687         (Maybe Dec)     -- Nothing for lambda-bound variables, and  
    688                         -- for anything else TH can't figure out 
    689                         -- E.g. [| let x = 1 in $(do { d <- reify 'x; .. }) |] 
    690         Fixity 
     909       Name 
     910       Type 
     911       (Maybe Dec) 
     912       Fixity 
    691913 
     914  {- |  
     915  A type variable. 
     916   
     917  The @Type@ field contains the type which underlies the variable. 
     918  At present, this is always @'VarT' theName@, but future changes 
     919  may permit refinement of this. 
     920  -} 
    692921  | TyVarI      -- Scoped type variable 
    693922        Name 
    694923        Type    -- What it is bound to 
    695924  deriving( Show, Data, Typeable ) 
    696925 
    697 -- | 'InstanceDec' desribes a single instance of a class or type function 
     926{- |  
     927In 'ClassOpI' and 'DataConI', name of the parent class or type 
     928-} 
     929type ParentName = Name 
     930 
     931-- | In 'PrimTyConI', arity of the type constructor 
     932type Arity = Int 
     933 
     934-- | In 'PrimTyConI', is the type constructor unlifted? 
     935type Unlifted = Bool 
     936 
     937-- | 'InstanceDec' desribes a single instance of a class or type function. 
    698938-- It is just a 'Dec', but guaranteed to be one of the following: 
    699 --   InstanceD (with empty [Dec]) 
    700 --   DataInstD or NewtypeInstD (with empty derived [Name]) 
    701 --   TySynInstD 
     939-- 
     940--   * 'InstanceD' (with empty @['Dec']@) 
     941-- 
     942--   * 'DataInstD' or 'NewtypeInstD' (with empty derived @['Name']@) 
     943-- 
     944--   * 'TySynInstD' 
    702945type InstanceDec = Dec 
    703946 
    704947data Fixity          = Fixity Int FixityDirection 
    data Fixity = Fixity Int FixityDirection 
    706949data FixityDirection = InfixL | InfixR | InfixN 
    707950    deriving( Eq, Show, Data, Typeable ) 
    708951 
     952-- | Highest allowed operator precedence for 'Fixity' constructor (answer: 9) 
    709953maxPrecedence :: Int 
    710954maxPrecedence = (9::Int) 
    711955 
     956-- | Default fixity: @infixl 9@ 
    712957defaultFixity :: Fixity 
    713958defaultFixity = Fixity maxPrecedence InfixL 
    714959 
    715960 
    716 ----------------------------------------------------- 
    717 -- 
    718 --      The main syntax data types 
    719 -- 
    720 ----------------------------------------------------- 
    721  
    722 {- $infix #infix# 
     961{- 
    723962Note [Unresolved infix] 
    724963~~~~~~~~~~~~~~~~~~~~~~~ 
    725  
     964-} 
     965{- $infix #infix# 
    726966When implementing antiquotation for quasiquoters, one often wants 
    727967to parse strings into expressions: 
    728968 
    729 > parse :: String -> Maybe 'Exp' 
     969> parse :: String -> Maybe Exp 
    730970 
    731971But how should we parse @a + b * c@? If we don't know the fixities of 
    732972@+@ and @*@, we don't know whether to parse it as @a + (b * c)@ or @(a 
    reassociate the tree as necessary. 
    7811021 
    7821022-} 
    7831023 
     1024----------------------------------------------------- 
     1025-- 
     1026--      The main syntax data types 
     1027-- 
     1028----------------------------------------------------- 
     1029 
    7841030data Lit = CharL Char  
    7851031         | StringL String  
    7861032         | IntegerL Integer     -- ^ Used for overloaded and non-overloaded 
    data Pat 
    8091055  | InfixP Pat Name Pat           -- ^ @foo ({x :+ y}) = e@ 
    8101056  | UInfixP Pat Name Pat          -- ^ @foo ({x :+ y}) = e@ 
    8111057                                  -- 
    812                                   -- See Note [Unresolved infix] at "Language.Haskell.TH.Syntax#infix" 
     1058                                  -- See "Language.Haskell.TH.Syntax#infix" 
    8131059  | ParensP Pat                   -- ^ @{(p)}@ 
    8141060                                  -- 
    815                                   -- See Note [Unresolved infix] at "Language.Haskell.TH.Syntax#infix" 
     1061                                  -- See "Language.Haskell.TH.Syntax#infix" 
    8161062  | TildeP Pat                    -- ^ @{ ~p }@ 
    8171063  | BangP Pat                     -- ^ @{ !p }@ 
    8181064  | AsP Name Pat                  -- ^ @{ x \@ p }@ 
    data Clause = Clause [Pat] Body [Dec] 
    8311077                                  -- ^ @f { p1 p2 = body where decs }@ 
    8321078    deriving( Show, Eq, Data, Typeable ) 
    8331079  
    834 -- | The 'CompE' constructor represents a list comprehension, and  
    835 -- takes a ['Stmt'].  The result expression of the comprehension is 
    836 -- the *last* of these, and should be a 'NoBindS'. 
    837 -- 
    838 -- E.g. translation: 
    839 -- 
    840 -- > [ f x | x <- xs ] 
    841 -- 
    842 -- > CompE [BindS (VarP x) (VarE xs), NoBindS (AppE (VarE f) (VarE x))] 
    8431080data Exp  
    8441081  = VarE Name                          -- ^ @{ x }@ 
    8451082  | ConE Name                          -- ^ @data T1 = C1 t1 t2; p = {C1} e1 e2  @ 
    data Exp 
    8471084  | AppE Exp Exp                       -- ^ @{ f x }@ 
    8481085 
    8491086  | InfixE (Maybe Exp) Exp (Maybe Exp) -- ^ @{x + y} or {(x+)} or {(+ x)} or {(+)}@ 
    850     -- 
     1087 
    8511088    -- It's a bit gruesome to use an Exp as the 
    8521089    -- operator, but how else can we distinguish 
    8531090    -- constructors from non-constructors? 
    data Exp 
    8561093 
    8571094  | UInfixE Exp Exp Exp                -- ^ @{x + y}@ 
    8581095                                       -- 
    859                                        -- See Note [Unresolved infix] at "Language.Haskell.TH.Syntax#infix" 
     1096                                       -- See "Language.Haskell.TH.Syntax#infix" 
    8601097  | ParensE Exp                        -- ^ @{ (e) }@ 
    8611098                                       -- 
    862                                        -- See Note [Unresolved infix] at "Language.Haskell.TH.Syntax#infix" 
     1099                                       -- See "Language.Haskell.TH.Syntax#infix" 
    8631100  | LamE [Pat] Exp                     -- ^ @{ \ p1 p2 -> e }@ 
    8641101  | TupE [Exp]                         -- ^ @{ (e1,e2) }  @ 
    8651102  | UnboxedTupE [Exp]                  -- ^ @{ (# e1,e2 #) }  @ 
    data Exp 
    8671104  | LetE [Dec] Exp                     -- ^ @{ let x=e1;   y=e2 in e3 }@ 
    8681105  | CaseE Exp [Match]                  -- ^ @{ case e of m1; m2 }@ 
    8691106  | DoE [Stmt]                         -- ^ @{ do { p <- e1; e2 }  }@ 
    870   | CompE [Stmt]                       -- ^ @{ [ (x,y) | x <- xs, y <- ys ] }@ 
     1107  | CompE [Stmt]                       -- ^ @{ [ (x,y) | x <- xs, y <- ys ] }@  
     1108      -- 
     1109      -- The result expression of the comprehension is 
     1110      -- the /last/ of the @'Stmt'@s, and should be a 'NoBindS'. 
     1111      -- 
     1112      -- E.g. translation: 
     1113      -- 
     1114      -- > [ f x | x <- xs ] 
     1115      -- 
     1116      -- > CompE [BindS (VarP x) (VarE xs), NoBindS (AppE (VarE f) (VarE x))] 
     1117 
    8711118  | ArithSeqE Range                    -- ^ @{ [ 1 ,2 .. 10 ] }@ 
    8721119  | ListE [ Exp ]                      -- ^ @{ [1,2,3] }@ 
    8731120  | SigE Exp Type                      -- ^ @{ e :: t }@ 
    type FieldExp = (Name,Exp) 
    8801127-- Omitted: implicit parameters 
    8811128 
    8821129data Body 
    883   = GuardedB [(Guard,Exp)]   -- ^ @f p { | e1 = e2 | e3 = e4 } where ds@ 
     1130  = GuardedB [(Guard,Exp)]   -- ^ @f p { | e1 = e2  
     1131                                 --      | e3 = e4 }  
     1132                                 -- where ds@ 
    8841133  | NormalB Exp              -- ^ @f p { = e } where ds@ 
    8851134  deriving( Show, Eq, Data, Typeable ) 
    8861135 
    8871136data Guard 
    888   = NormalG Exp 
    889   | PatG [Stmt] 
     1137  = NormalG Exp -- ^ @f x { | odd x } = x@ 
     1138  | PatG [Stmt] -- ^ @f x { | Just y <- x, Just z <- y } = z@ 
    8901139  deriving( Show, Eq, Data, Typeable ) 
    8911140 
    8921141data Stmt 
    data Dec 
    9151164  | InstanceD Cxt Type [Dec]      -- ^ @{ instance Show w => Show [w] 
    9161165                                  --       where ds }@ 
    9171166  | SigD Name Type                -- ^ @{ length :: [a] -> Int }@ 
    918   | ForeignD Foreign 
     1167  | ForeignD Foreign              -- ^ @{ foreign import ... } 
     1168                                  --{ foreign export ... }@ 
    9191169 
    9201170  | InfixD Fixity Name            -- ^ @{ infix 3 foo }@ 
    9211171 
    9221172  -- | pragmas 
    923   | PragmaD Pragma                -- ^ @{ {-# INLINE [1] foo #-} }@ 
     1173  | PragmaD Pragma                -- ^ @{ {\-# INLINE [1] foo #-\} }@ 
    9241174 
    9251175  -- | type families (may also appear in [Dec] of 'ClassD' and 'InstanceD') 
    9261176  | FamilyD FamFlavour Name  
    data Con = NormalC Name [StrictType] -- ^ @C Int a@ 
    9851235type StrictType = (Strict, Type) 
    9861236type VarStrictType = (Name, Strict, Type) 
    9871237 
    988 data Type = ForallT [TyVarBndr] Cxt Type  -- ^ @forall <vars>. <ctxt> -> <type>@ 
     1238data Type = ForallT [TyVarBndr] Cxt Type  -- ^ @forall \<vars\>. \<ctxt\> -> \<type\>@ 
    9891239          | AppT Type Type                -- ^ @T a b@ 
    9901240          | SigT Type Kind                -- ^ @t :: k@ 
    9911241          | VarT Name                     -- ^ @a@