Ticket #4429: 0001-First-effort-on-documentation.patch

File 0001-First-effort-on-documentation.patch, 26.1 KB (added by reinerp, 4 years ago)
  • Language/Haskell/TH.hs

    From 80c78cb3b6809e6064ea634beff499cb03ad7dbc Mon Sep 17 00:00:00 2001
    From: Reiner Pope <[email protected]>
    Date: Mon, 5 Sep 2011 12:47:12 +1000
    Subject: [PATCH] First effort on documentation
    
    ---
     Language/Haskell/TH.hs        |   37 +++-
     Language/Haskell/TH/Syntax.hs |  485 +++++++++++++++++++++++++++++++++--------
     2 files changed, 419 insertions(+), 103 deletions(-)
    
    diff --git a/Language/Haskell/TH.hs b/Language/Haskell/TH.hs
    index 9f69c32..506418f 100644
    a b For other documentation, refer to: 
    66-} 
    77module Language.Haskell.TH( 
    88        -- * The monad and its operations 
    9         Q, runQ,  
    10         report,           -- :: Bool -> String -> Q () 
     9        Q, runQ, 
     10        -- ** Administration: errors, locations and IO 
     11        reportError,      -- :: String -> Q () 
     12        reportWarning,    -- :: String -> Q () 
    1113        recover,          -- :: Q a -> Q a -> Q a 
    12         reify,            -- :: Name -> Q Info 
    13         location,         -- :: Q Location 
     14        location,         -- :: Q Loc 
     15        Loc(..), 
    1416        runIO,            -- :: IO a -> Q a 
    15         lookupTypeName, lookupValueName, 
    16         isInstance, reifyInstances, 
     17        -- ** Querying the compiler 
     18        -- *** Reify 
     19        reify,            -- :: Name -> Q Info 
     20        Info(..), 
     21        InstanceDec, 
     22        ParentName, 
     23        Arity, 
     24        Unlifted, 
     25        -- *** Name lookup 
     26        lookupTypeName,   -- :: String -> Q (Maybe Name) 
     27        lookupValueName,  -- :: String -> Q (Maybe Name) 
     28        -- *** Instance lookup 
     29        reifyInstances,   -- :: Name -> [Type] -> Q [InstanceDec] 
     30        isInstance,       -- :: Name -> [Type] -> Q Bool 
    1731 
    1832        -- * Names 
    19         Name, NameSpace,        -- Abstract 
     33        Name,           -- Abstract 
     34        -- ** Constructing names 
    2035        mkName,         -- :: String -> Name 
    2136        newName,        -- :: String -> Q Name 
     37        -- ** Deconstructing names 
    2238        nameBase,       -- :: Name -> String 
    2339        nameModule,     -- :: Name -> Maybe String 
     40        -- ** Built-in names 
    2441        tupleTypeName, tupleDataName,   -- Int -> Name 
     42        unboxedTupleTypeName, unboxedTupleDataName, -- Int -> Name 
    2543         
    2644    -- * The algebraic data types 
    2745    -- | The lowercase versions (/syntax operators/) of these constructors are 
    module Language.Haskell.TH( 
    3149        Pred(..), Match(..), Clause(..), Body(..), Guard(..), Stmt(..), 
    3250        Range(..), Lit(..), Pat(..), FieldExp, FieldPat,  
    3351        Strict(..), Foreign(..), Callconv(..), Safety(..), Pragma(..), 
    34         InlineSpec(..), FunDep(..), FamFlavour(..), Info(..), Loc(..), 
     52        InlineSpec(..), FunDep(..), FamFlavour(..),  
    3553        Fixity(..), FixityDirection(..), defaultFixity, maxPrecedence, 
    36  
     54  
     55    -- * Library functions 
    3756    -- * Library functions 
    3857    -- ** Abbreviations 
    3958        InfoQ, ExpQ, DecQ, DecsQ, ConQ, TypeQ, CxtQ, PredQ, MatchQ, ClauseQ, BodyQ, 
  • Language/Haskell/TH/Syntax.hs

    diff --git a/Language/Haskell/TH/Syntax.hs b/Language/Haskell/TH/Syntax.hs
    index 5c70fae..fda9ca4 100644
    a b  
    2323module Language.Haskell.TH.Syntax( 
    2424        Quasi(..), Lift(..), liftString, 
    2525 
     26        -- * The monad and its operations 
    2627        Q, runQ,  
    27         report, recover, reify,  
     28        -- ** Administration: errors, locations and IO 
     29        reportError, reportWarning, 
     30        recover, 
     31        location,  
     32        Loc(..), CharPos, 
     33        runIO, 
     34        -- ** Querying the compiler 
     35        -- *** Reify 
     36        reify,  
     37        Info(..), 
     38        InstanceDec, 
     39        ParentName, 
     40        Arity, 
     41        Unlifted, 
     42        -- *** Name lookup 
     43        -- $namelookup 
    2844        lookupTypeName, lookupValueName, 
    29         location, runIO, 
    30         isInstance, reifyInstances, 
     45        -- *** Instance lookup 
     46        reifyInstances, isInstance, 
    3147 
    3248        -- * Names 
    33         Name(..), mkName, newName, nameBase, nameModule, 
     49        -- $namecapture 
     50        Name(..),  
     51        -- ** Constructing names 
     52        mkName, newName,  
     53        -- ** Deconstructing names 
     54        nameBase, nameModule, 
    3455        showName, showName', NameIs(..), 
    35  
     56        -- ** Built-in names 
     57        tupleTypeName, tupleDataName, 
     58        unboxedTupleTypeName, unboxedTupleDataName, 
     59         
    3660        -- * The algebraic data types 
    37         -- $infix 
    38         Dec(..), Exp(..), Con(..), Type(..), TyVarBndr(..), Kind(..),Cxt, 
    39         Pred(..), Match(..),  Clause(..), Body(..), Guard(..), Stmt(..), 
    40         Range(..), Lit(..), Pat(..), FieldExp, FieldPat,  
    41         Strict(..), Foreign(..), Callconv(..), Safety(..), Pragma(..), 
    42         InlineSpec(..), StrictType, VarStrictType, FunDep(..), FamFlavour(..), 
    43         Info(..), Loc(..), CharPos, 
     61        -- ** Declarations 
     62        Dec(..), 
     63        Con(..), 
     64        StrictType, VarStrictType, Strict(..),  
     65        Foreign(..), Callconv(..), Safety(..),  
    4466        Fixity(..), FixityDirection(..), defaultFixity, maxPrecedence, 
     67        Pragma(..), InlineSpec(..),      
     68        FunDep(..),  
     69        FamFlavour(..), 
     70        -- ** Expressions 
     71        Exp(..), 
     72        Match(..), Clause(..), Body(..), Guard(..), Stmt(..), 
     73        FieldExp, 
     74        Lit(..),   
     75        Range(..), 
     76        -- ** Patterns 
     77        Pat(..), 
     78        FieldPat, 
     79        -- ** Types 
     80        Type(..),  
     81        TyVarBndr(..), Kind(..), Cxt, Pred(..), 
     82 
     83        -- * Unresolved infix 
     84        -- $infix 
    4585 
    4686        -- * Internal functions 
    4787        returnQ, bindQ, sequenceQ, 
    4888        NameFlavour(..), NameSpace (..),  
    4989        mkNameG_v, mkNameG_d, mkNameG_tc, Uniq, mkNameL, mkNameU, 
    50         tupleTypeName, tupleDataName, 
    51         unboxedTupleTypeName, unboxedTupleDataName, 
    5290        OccName, mkOccName, occString, 
    5391        ModName, mkModName, modString, 
    5492        PkgName, mkPkgName, pkgString 
    counter = unsafePerformIO (newIORef 0) 
    144182 
    145183newtype Q a = Q { unQ :: forall m. Quasi m => m a } 
    146184 
     185-- \"Runs\" the 'Q' monad. Normal users of Template Haskell 
     186-- should not need this function, as the splice brackets @$( ... )@ 
     187-- are the usual way of running a 'Q' computation. 
     188-- 
     189-- This function is primarily used in GHC internals, and for debugging 
     190-- splices by running them in 'IO'.  
     191-- 
     192-- Note that many functions in 'Q', such as 'reify' and other compiler 
     193-- queries, are not supported when running 'Q' in 'IO'; these operations 
     194-- simply fail at runtime. Indeed, the only operations guaranteed to succeed 
     195-- are 'newName', 'runIO', 'reportError' and 'reportWarning'. 
    147196runQ :: Quasi m => Q a -> m a 
    148197runQ (Q m) = m 
    149198 
    instance Applicative Q where 
    162211 
    163212---------------------------------------------------- 
    164213-- Packaged versions for the programmer, hiding the Quasi-ness 
     214 
     215{- |  
     216Generate a fresh name, which cannot be captured.  
     217 
     218For example, this: 
     219 
     220@f = $(do 
     221  nm1 <- newName \"x\" 
     222  let nm2 = 'mkName' \"x\" 
     223  return ('LamE' ['VarP' nm1] (LamE [VarP nm2] ('VarE' nm1))) 
     224 )@ 
     225 
     226will produce the splice 
     227 
     228>f = \x0 -> \x -> x0 
     229 
     230In particular, the occurrence @VarE nm1@ refers to the binding @VarP nm1@, 
     231and is not captured by the binding @VarP nm2@. 
     232 
     233Although names generated by @newName@ cannot /be captured/, they can 
     234/capture/ other names. For example, this: 
     235 
     236>g = $(do 
     237>  nm1 <- newName "x" 
     238>  let nm2 = mkName "x" 
     239>  return (LamE [VarP nm2] (LamE [VarP nm1] (VarE nm2))) 
     240> ) 
     241 
     242will produce the splice 
     243 
     244>g = \x -> \x0 -> x0 
     245 
     246since the occurrence @VarE nm2@ is captured by the innermost binding 
     247of @x@, namely @VarP nm1@. 
     248-} 
    165249newName :: String -> Q Name 
    166250newName s = Q (qNewName s) 
    167251 
     252-- | Report an error (True) or warning (False),  
     253-- but carry on; use 'fail' to stop. 
    168254report  :: Bool -> String -> Q () 
    169255report b s = Q (qReport b s) 
     256{-# DEPRECATED report "Use reportError or reportWarning instead" #-} 
     257 
     258-- | Report an error to the user, but allow the current splice's computation to carry on. To abort the computation, use 'fail'. 
     259reportError :: String -> Q () 
     260reportError = report True 
     261 
     262-- | Report a warning to the user, and carry on. 
     263reportWarning :: String -> Q () 
     264reportWarning = report False 
    170265 
    171 recover :: Q a -- ^ recover with this one 
    172         -> Q a -- ^ failing action 
     266-- | Recover from errors raised by 'reportError' or 'fail'. 
     267recover :: Q a -- ^ handler to invoke on failure 
     268        -> Q a -- ^ computation to run 
    173269        -> Q a 
    174270recover (Q r) (Q m) = Q (qRecover r m) 
    175271 
    recover (Q r) (Q m) = Q (qRecover r m) 
    178274lookupName :: Bool -> String -> Q (Maybe Name) 
    179275lookupName ns s = Q (qLookupName ns s) 
    180276 
    181 lookupTypeName, lookupValueName :: String -> Q (Maybe Name) 
     277-- | Look up the given name in the (type namespace of the) current splice's scope. See "Language.Haskell.TH.Syntax#namelookup" for more details. 
     278lookupTypeName :: String -> Q (Maybe Name) 
    182279lookupTypeName  s = Q (qLookupName True s) 
     280 
     281-- | Look up the given name in the (value namespace of the) current splice's scope. See "Language.Haskell.TH.Syntax#namelookup" for more details. 
     282lookupValueName :: String -> Q (Maybe Name) 
    183283lookupValueName s = Q (qLookupName False s) 
    184284 
    185 -- | 'reify' looks up information about the 'Name' 
     285{- 
     286Note [Name lookup] 
     287~~~~~~~~~~~~~~~~~~ 
     288-} 
     289{- $namelookup #namelookup# 
     290The functions 'lookupTypeName' and 'lookupValueName' provide 
     291a way to query the current splice's context for what names 
     292are in scope. The function 'lookupTypeName' queries the type 
     293namespace, whereas 'lookupValueName' queries the value namespace, 
     294but the functions are otherwise identical. 
     295 
     296A call @lookupValueName s@ will check if there is a value 
     297with name @s@ in scope at the current splice's location. If 
     298there is, the @Name@ of this value is returned; 
     299if not, then @Nothing@ is returned. 
     300 
     301The returned name cannot be \"captured\".  
     302For example: 
     303 
     304> f = "global" 
     305> g = $( do 
     306>          Just nm <- lookupValueName "f" 
     307>          [| let f = "local" in $( varE nm ) |] 
     308 
     309In this case, @g = \"global\"@; the call to @lookupValueName@ 
     310returned the global @f@, and this name was /not/ captured by 
     311the local definition of @f@. 
     312 
     313The lookup is performed in the context of the /top-level/ splice 
     314being run. For example: 
     315 
     316> f = "global" 
     317> g = $( [| let f = "local" in  
     318>            $(do 
     319>                Just nm <- lookupValueName "f" 
     320>                varE nm 
     321>             ) |] ) 
     322 
     323Again in this example, @g = \"global\"@, because the call to 
     324@lookupValueName@ queries the context of the outer-most @$(...)@. 
     325 
     326Operators should be queried without any surrounding parentheses, like so: 
     327 
     328> lookupValueName "+" 
     329 
     330Qualified names are also supported, like so: 
     331 
     332> lookupValueName "Prelude.+" 
     333> lookupValueName "Prelude.map" 
     334 
     335-} 
     336 
     337 
     338{- | 'reify' looks up information about the 'Name'. 
     339 
     340It is sometimes useful to construct the argument name using 'lookupTypeName' or 'lookupValueName' 
     341to ensure that we are reifying from the right namespace. For instance, in this context: 
     342 
     343> data D = D 
     344 
     345which @D@ does @reify (mkName \"D\")@ return information about? (Answer: @D@-the-type, but don't rely on it.) 
     346To ensure we get information about @D@-the-value, use 'lookupValueName': 
     347 
     348> do 
     349>   Just nm <- lookupValueName "D" 
     350>   reify nm 
     351 
     352and to get information about @D@-the-type, use 'lookupTypeName'. 
     353-} 
    186354reify :: Name -> Q Info 
    187355reify v = Q (qReify v) 
    188356 
    189 -- | 'classInstances' looks up instaces of a class 
    190 reifyInstances :: Name -> [Type] -> Q [Dec] 
     357{- | @reifyInstances nm tys@ returns a list of visible instances of @nm tys@. That is,  
     358if @nm@ is the name of a type class, then all instances of this class at the types @tys@ 
     359are returned. Alternatively, if @nm@ is the name of a data family or type family, 
     360all instances of this family at the types @tys@ are returned. 
     361-} 
     362reifyInstances :: Name -> [Type] -> Q [InstanceDec] 
    191363reifyInstances cls tys = Q (qReifyInstances cls tys) 
    192364 
     365-- | Is the list of instances returned by 'reifyInstances' nonempty? 
    193366isInstance :: Name -> [Type] -> Q Bool 
    194367isInstance nm tys = do { decs <- reifyInstances nm tys 
    195368                       ; return (not (null decs)) } 
    196369 
    197 -- | 'location' gives you the 'Location' at which this 
    198 -- computation is spliced. 
     370-- | The location at which this computation is spliced. 
    199371location :: Q Loc 
    200372location = Q qLocation 
    201373 
    occString (OccName occ) = occ 
    352524----------------------------------------------------- 
    353525--               Names 
    354526----------------------------------------------------- 
    355  
    356 -- | 
     527--  
    357528-- For "global" names ('NameG') we need a totally unique name, 
    358529-- so we must include the name-space of the thing 
    359530-- 
    occString (OccName occ) = occ 
    377548-- The 'map' will be a NameG, and 'x' wil be a NameL 
    378549-- 
    379550-- These Names should never appear in a binding position in a TH syntax tree 
     551 
     552{- $namecapture #namecapture# 
     553Much of 'Name' API is concerned with the problem of /name capture/, which 
     554can be seen in the following example. 
     555 
     556> f expr = [| let x = 0 in $expr |] 
     557> ... 
     558> g x = $( f [| x |] ) 
     559> h y = $( f [| y |] ) 
     560 
     561A naive desugaring of this would yield: 
     562 
     563> g x = let x = 0 in x 
     564> h y = let x = 0 in y 
     565 
     566All of a sudden, @g@ and @h@ have different meanings! In this case, 
     567we say that the @x@ in the RHS of @g@ has been /captured/ 
     568by the binding of @x@ in @f@. 
     569 
     570What we actually want is for the @x@ in @f@ to be distinct from the 
     571@x@ in @g@, so we get the following desugaring: 
     572 
     573> g x = let x' = 0 in x 
     574> h y = let x' = 0 in y 
     575 
     576which avoids name capture as desired.  
     577 
     578In the general case, we say that a @Name@ can be captured if 
     579the thing it refers to can be changed by adding new declarations. 
     580-} 
     581 
     582{- | 
     583An abstract type representing names in the syntax tree. 
     584 
     585'Name's can be constructed in several ways, which come with different 
     586name-capture guarantees (see "Language.Haskell.TH.Syntax#namecapture" for 
     587an explanation of name capture): 
     588 
     589  * the built-in syntax @'f@ and @''T@ can be used to construct names,  
     590    The expression @'f@ gives a @Name@ which refers to the value @f@  
     591    currently in scope, and @''T@ gives a @Name@ which refers to the 
     592    type @T@ currently in scope. These names can never be captured. 
     593     
     594  * 'lookupValueName' and 'lookupTypeName' are similar to @'f@ and  
     595     @''T@ respectively, but the @Name@s are looked up at the point 
     596     where the current splice is being run. These names can never be 
     597     captured. 
     598 
     599  * 'newName' monadically generates a new name, which can never 
     600     be captured. 
     601      
     602  * 'mkName' generates a capturable name. 
     603 
     604Names constructed using @newName@ and @mkName@ may be used in bindings 
     605(such as @let x = ...@ or @\x -> ...@), but names constructed using 
     606@lookupValueName@, @lookupTypeName@, @'f@, @''T@ may not. 
     607-} 
    380608data Name = Name OccName NameFlavour deriving (Typeable, Data) 
    381609 
    382610data NameFlavour 
    data NameSpace = VarName -- ^ Variables 
    441669 
    442670type Uniq = Int 
    443671 
    444 -- | Base, unqualified name. 
     672-- | The name without its module prefix 
    445673nameBase :: Name -> String 
    446674nameBase (Name occ _) = occString occ 
    447675 
     676-- | Module prefix of a name, if it exists 
    448677nameModule :: Name -> Maybe String 
    449678nameModule (Name _ (NameQ m))     = Just (modString m) 
    450679nameModule (Name _ (NameG _ _ m)) = Just (modString m) 
    451680nameModule _                      = Nothing 
    452681 
     682{- |  
     683Generate a capturable name. Occurrences of such names will be 
     684resolved according to the Haskell scoping rules at the occurrence 
     685site. 
     686 
     687For example: 
     688 
     689> f = [| pi + $(varE (mkName "pi")) |] 
     690> ... 
     691> g = let pi = 3 in $f 
     692 
     693In this case, @g@ is desugared to 
     694 
     695> g = Prelude.pi + 3 
     696 
     697Note that @mkName@ may be used with qualified names: 
     698 
     699> mkName "Prelude.pi" 
     700 
     701See also 'Language.Haskell.TH.Lib.dyn' for a useful combinator. The above example could 
     702be rewritten using 'dyn' as 
     703 
     704> f = [| pi + $(dyn "pi") |] 
     705-} 
    453706mkName :: String -> Name 
    454 -- ^ The string can have a '.', thus "Foo.baz", 
     707-- The string can have a '.', thus "Foo.baz", 
    455708-- giving a dynamically-bound qualified name, 
    456709-- in which case we want to generate a NameQ 
    457710-- 
    instance Show Name where 
    578831  show = showName 
    579832 
    580833-- Tuple data and type constructors 
    581 tupleDataName :: Int -> Name    -- ^ Data constructor 
    582 tupleTypeName :: Int -> Name    -- ^ Type constructor 
     834-- | Tuple data constructor 
     835tupleDataName :: Int -> Name 
     836-- | Tuple type constructor 
     837tupleTypeName :: Int -> Name 
    583838 
    584839tupleDataName 0 = mk_tup_name 0 DataName 
    585840tupleDataName 1 = error "tupleDataName 1" 
    mk_tup_name n_commas space 
    597852    tup_mod = mkModName "GHC.Tuple" 
    598853 
    599854-- Unboxed tuple data and type constructors 
    600 unboxedTupleDataName :: Int -> Name    -- ^ Data constructor 
    601 unboxedTupleTypeName :: Int -> Name    -- ^ Type constructor 
     855-- | Unboxed tuple data constructor 
     856unboxedTupleDataName :: Int -> Name 
     857-- | Unboxed tuple type constructor 
     858unboxedTupleTypeName :: Int -> Name 
    602859 
    603860unboxedTupleDataName 0 = error "unboxedTupleDataName 0" 
    604861unboxedTupleDataName 1 = error "unboxedTupleDataName 1" 
    data Loc 
    628885        , loc_start    :: CharPos 
    629886        , loc_end      :: CharPos } 
    630887 
    631 type CharPos = (Int, Int)       -- Line and character position 
     888type CharPos = (Int, Int)       -- ^ Line and character position 
    632889 
    633890 
    634891----------------------------------------------------- 
    type CharPos = (Int, Int) -- Line and character position 
    639896 
    640897-- | Obtained from 'reify' in the 'Q' Monad. 
    641898data Info 
    642   = -- | A class is reified to its declaration  
    643     --   and a list of its instances 
    644     ClassI  
    645         Dec             -- Declaration of the class 
    646         [InstanceDec]   -- The instances of that class 
    647  
     899  =  
     900  -- | A class, with a list of its visible instances 
     901  ClassI  
     902      Dec 
     903      [InstanceDec] 
     904   
     905  -- | A class method 
    648906  | ClassOpI 
    649         Name    -- The class op itself 
    650         Type    -- Type of the class-op (fully polymoprhic) 
    651         Name    -- Name of the parent class 
    652         Fixity 
    653  
     907       Name 
     908       Type 
     909       ParentName 
     910       Fixity 
     911   
     912  -- | A \"plain\" type constructor. \"Fancier\" type constructors are returned using 'PrimTyConI' or 'FamilyI' as appropriate 
    654913  | TyConI  
    655914        Dec 
    656915 
    657   | FamilyI     -- Type/data families 
     916  -- | A type or data family, with a list of its visible instances 
     917  | FamilyI  
    658918        Dec 
    659919        [InstanceDec] 
    660  
    661   | PrimTyConI  -- Ones that can't be expressed with a data type  
    662                 -- decl, such as (->), Int# 
    663         Name  
    664         Int     -- Arity 
    665         Bool    -- False => lifted type; True => unlifted 
    666  
     920   
     921  -- | A \"primitive\" type constructor, which can't be expressed with a 'Dec'. Examples: @(->)@, @Int#@. 
     922  | PrimTyConI  
     923       Name 
     924       Arity 
     925       Unlifted 
     926   
     927  -- | A data constructor 
    667928  | DataConI  
    668         Name    -- The data con itself 
    669         Type    -- Type of the constructor (fully polymorphic) 
    670         Name    -- Name of the parent TyCon 
    671         Fixity 
     929       Name 
     930       Type 
     931       ParentName 
     932       Fixity 
    672933 
     934  {- |  
     935  A \"value\" variable (as opposed to a type variable, see 'TyVarI'). 
     936   
     937  The @Maybe Dec@ field contains @Just@ the declaration which  
     938  defined the variable -- including the RHS of the declaration --  
     939  or else @Nothing@, in the case where the RHS is unavailable to 
     940  the compiler. At present, this value is _always_ @Nothing@: 
     941  returning the RHS has not yet been implemented because of 
     942  lack of interest. 
     943  -} 
    673944  | VarI  
    674         Name    -- The variable itself 
    675         Type  
    676         (Maybe Dec)     -- Nothing for lambda-bound variables, and  
    677                         -- for anything else TH can't figure out 
    678                         -- E.g. [| let x = 1 in $(do { d <- reify 'x; .. }) |] 
    679         Fixity 
     945       Name 
     946       Type 
     947       (Maybe Dec) 
     948       Fixity 
    680949 
     950  {- |  
     951  A type variable. 
     952   
     953  The @Type@ field contains the type which underlies the variable. 
     954  At present, this is always @'VarT' theName@, but future changes 
     955  may permit refinement of this. 
     956  -} 
    681957  | TyVarI      -- Scoped type variable 
    682958        Name 
    683959        Type    -- What it is bound to 
    684960  deriving( Show, Data, Typeable ) 
    685961 
    686 -- | 'InstanceDec' desribes a single instance of a class or type function 
     962{- |  
     963In 'ClassOpI' and 'DataConI', name of the parent class or type 
     964-} 
     965type ParentName = Name 
     966 
     967-- | In 'PrimTyConI', arity of the type constructor 
     968type Arity = Int 
     969 
     970-- | In 'PrimTyConI', is the type constructor unlifted? 
     971type Unlifted = Bool 
     972 
     973-- | 'InstanceDec' desribes a single instance of a class or type function. 
    687974-- It is just a 'Dec', but guaranteed to be one of the following: 
    688 --   InstanceD (with empty [Dec]) 
    689 --   DataInstD or NewtypeInstD (with empty derived [Name]) 
    690 --   TySynInstD 
     975-- 
     976--   * 'InstanceD' (with empty @['Dec']@) 
     977-- 
     978--   * 'DataInstD' or 'NewtypeInstD' (with empty derived @['Name']@) 
     979-- 
     980--   * 'TySynInstD' 
    691981type InstanceDec = Dec 
    692982 
    693983data Fixity          = Fixity Int FixityDirection 
    data Fixity = Fixity Int FixityDirection 
    695985data FixityDirection = InfixL | InfixR | InfixN 
    696986    deriving( Eq, Show, Data, Typeable ) 
    697987 
     988-- | Highest allowed operator precedence for 'Fixity' constructor (answer: 9) 
    698989maxPrecedence :: Int 
    699990maxPrecedence = (9::Int) 
    700991 
     992-- | Default fixity: @infixl 9@ 
    701993defaultFixity :: Fixity 
    702994defaultFixity = Fixity maxPrecedence InfixL 
    703995 
    704996 
    705 ----------------------------------------------------- 
    706 -- 
    707 --      The main syntax data types 
    708 -- 
    709 ----------------------------------------------------- 
    710  
    711 {- $infix #infix# 
     997{- 
    712998Note [Unresolved infix] 
    713999~~~~~~~~~~~~~~~~~~~~~~~ 
    714  
     1000-} 
     1001{- $infix #infix# 
    7151002When implementing antiquotation for quasiquoters, one often wants 
    7161003to parse strings into expressions: 
    7171004 
    718 > parse :: String -> Maybe 'Exp' 
     1005> parse :: String -> Maybe Exp 
    7191006 
    7201007But how should we parse @a + b * c@? If we don't know the fixities of 
    7211008@+@ and @*@, we don't know whether to parse it as @a + (b * c)@ or @(a 
    reassociate the tree as necessary. 
    7701057 
    7711058-} 
    7721059 
     1060----------------------------------------------------- 
     1061-- 
     1062--      The main syntax data types 
     1063-- 
     1064----------------------------------------------------- 
     1065 
    7731066data Lit = CharL Char  
    7741067         | StringL String  
    7751068         | IntegerL Integer     -- ^ Used for overloaded and non-overloaded 
    data Pat 
    7981091  | InfixP Pat Name Pat           -- ^ @foo ({x :+ y}) = e@ 
    7991092  | UInfixP Pat Name Pat          -- ^ @foo ({x :+ y}) = e@ 
    8001093                                  -- 
    801                                   -- See Note [Unresolved infix] at "Language.Haskell.TH.Syntax#infix" 
     1094                                  -- See "Language.Haskell.TH.Syntax#infix" 
    8021095  | ParensP Pat                   -- ^ @{(p)}@ 
    8031096                                  -- 
    804                                   -- See Note [Unresolved infix] at "Language.Haskell.TH.Syntax#infix" 
     1097                                  -- See "Language.Haskell.TH.Syntax#infix" 
    8051098  | TildeP Pat                    -- ^ @{ ~p }@ 
    8061099  | BangP Pat                     -- ^ @{ !p }@ 
    8071100  | AsP Name Pat                  -- ^ @{ x \@ p }@ 
    data Clause = Clause [Pat] Body [Dec] 
    8201113                                  -- ^ @f { p1 p2 = body where decs }@ 
    8211114    deriving( Show, Eq, Data, Typeable ) 
    8221115  
    823 -- | The 'CompE' constructor represents a list comprehension, and  
    824 -- takes a ['Stmt'].  The result expression of the comprehension is 
    825 -- the *last* of these, and should be a 'NoBindS'. 
    826 -- 
    827 -- E.g. translation: 
    828 -- 
    829 -- > [ f x | x <- xs ] 
    830 -- 
    831 -- > CompE [BindS (VarP x) (VarE xs), NoBindS (AppE (VarE f) (VarE x))] 
    8321116data Exp  
    8331117  = VarE Name                          -- ^ @{ x }@ 
    8341118  | ConE Name                          -- ^ @data T1 = C1 t1 t2; p = {C1} e1 e2  @ 
    data Exp 
    8361120  | AppE Exp Exp                       -- ^ @{ f x }@ 
    8371121 
    8381122  | InfixE (Maybe Exp) Exp (Maybe Exp) -- ^ @{x + y} or {(x+)} or {(+ x)} or {(+)}@ 
    839     -- 
     1123 
    8401124    -- It's a bit gruesome to use an Exp as the 
    8411125    -- operator, but how else can we distinguish 
    8421126    -- constructors from non-constructors? 
    data Exp 
    8451129 
    8461130  | UInfixE Exp Exp Exp                -- ^ @{x + y}@ 
    8471131                                       -- 
    848                                        -- See Note [Unresolved infix] at "Language.Haskell.TH.Syntax#infix" 
     1132                                       -- See "Language.Haskell.TH.Syntax#infix" 
    8491133  | ParensE Exp                        -- ^ @{ (e) }@ 
    8501134                                       -- 
    851                                        -- See Note [Unresolved infix] at "Language.Haskell.TH.Syntax#infix" 
     1135                                       -- See "Language.Haskell.TH.Syntax#infix" 
    8521136  | LamE [Pat] Exp                     -- ^ @{ \ p1 p2 -> e }@ 
    8531137  | TupE [Exp]                         -- ^ @{ (e1,e2) }  @ 
    8541138  | UnboxedTupE [Exp]                  -- ^ @{ (# e1,e2 #) }  @ 
    data Exp 
    8561140  | LetE [Dec] Exp                     -- ^ @{ let x=e1;   y=e2 in e3 }@ 
    8571141  | CaseE Exp [Match]                  -- ^ @{ case e of m1; m2 }@ 
    8581142  | DoE [Stmt]                         -- ^ @{ do { p <- e1; e2 }  }@ 
    859   | CompE [Stmt]                       -- ^ @{ [ (x,y) | x <- xs, y <- ys ] }@ 
     1143  | CompE [Stmt]                       -- ^ @{ [ (x,y) | x <- xs, y <- ys ] }@  
     1144      -- 
     1145      -- The result expression of the comprehension is 
     1146      -- the /last/ of the @'Stmt'@s, and should be a 'NoBindS'. 
     1147      -- 
     1148      -- E.g. translation: 
     1149      -- 
     1150      -- > [ f x | x <- xs ] 
     1151      -- 
     1152      -- > CompE [BindS (VarP x) (VarE xs), NoBindS (AppE (VarE f) (VarE x))] 
     1153 
    8601154  | ArithSeqE Range                    -- ^ @{ [ 1 ,2 .. 10 ] }@ 
    8611155  | ListE [ Exp ]                      -- ^ @{ [1,2,3] }@ 
    8621156  | SigE Exp Type                      -- ^ @{ e :: t }@ 
    type FieldExp = (Name,Exp) 
    8691163-- Omitted: implicit parameters 
    8701164 
    8711165data Body 
    872   = GuardedB [(Guard,Exp)]   -- ^ @f p { | e1 = e2 | e3 = e4 } where ds@ 
     1166  = GuardedB [(Guard,Exp)]   -- ^ @f p { | e1 = e2  
     1167                                 --      | e3 = e4 }  
     1168                                 -- where ds@ 
    8731169  | NormalB Exp              -- ^ @f p { = e } where ds@ 
    8741170  deriving( Show, Eq, Data, Typeable ) 
    8751171 
    8761172data Guard 
    877   = NormalG Exp 
    878   | PatG [Stmt] 
     1173  = NormalG Exp -- ^ @f x { | odd x } = x@ 
     1174  | PatG [Stmt] -- ^ @f x { | Just y <- x, Just z <- y } = z@ 
    8791175  deriving( Show, Eq, Data, Typeable ) 
    8801176 
    8811177data Stmt 
    data Dec 
    9041200  | InstanceD Cxt Type [Dec]      -- ^ @{ instance Show w => Show [w] 
    9051201                                  --       where ds }@ 
    9061202  | SigD Name Type                -- ^ @{ length :: [a] -> Int }@ 
    907   | ForeignD Foreign 
     1203  | ForeignD Foreign              -- ^ @{ foreign import ... } 
     1204                                  --{ foreign export ... }@ 
    9081205 
    9091206  -- | pragmas 
    910   | PragmaD Pragma                -- ^ @{ {-# INLINE [1] foo #-} }@ 
     1207  | PragmaD Pragma                -- ^ @{ {\-\# INLINE [1] foo #\-\} }@ 
    9111208 
    9121209  -- | type families (may also appear in [Dec] of 'ClassD' and 'InstanceD') 
    9131210  | FamilyD FamFlavour Name  
    data Con = NormalC Name [StrictType] -- ^ @C Int a@ 
    9671264type StrictType = (Strict, Type) 
    9681265type VarStrictType = (Name, Strict, Type) 
    9691266 
    970 data Type = ForallT [TyVarBndr] Cxt Type  -- ^ @forall <vars>. <ctxt> -> <type>@ 
     1267data Type = ForallT [TyVarBndr] Cxt Type  -- ^ @forall \<vars\>. \<ctxt\> -> \<type\>@ 
    9711268          | VarT Name                     -- ^ @a@ 
    9721269          | ConT Name                     -- ^ @T@ 
    9731270          | TupleT Int                    -- ^ @(,), (,,), etc.@