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.@