libghc-deriving-compat-doc 0.3.4-2 / usr / share / doc / libghc-deriving-compat-doc / html / deriving-compat.txt

-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Backports of GHC deriving extensions
--   
--   Provides Template Haskell functions that mimic deriving extensions
--   that were introduced or modified in recent versions of GHC. Currently,
--   the following typeclasses/extensions are covered:
--   
--   <ul>
--   <li>Deriving <tt>Bounded</tt></li>
--   <li>Deriving <tt>Enum</tt></li>
--   <li>Deriving <tt>Ix</tt></li>
--   <li>Deriving <tt>Eq</tt>, <tt>Eq1</tt>, and <tt>Eq2</tt></li>
--   <li>Deriving <tt>Ord</tt>, <tt>Ord1</tt>, and <tt>Ord2</tt></li>
--   <li>Deriving <tt>Read</tt>, <tt>Read1</tt>, and <tt>Read2</tt></li>
--   <li>Deriving <tt>Show</tt>, <tt>Show1</tt>, and <tt>Show2</tt></li>
--   <li><pre>DeriveFoldable</pre></li>
--   <li><pre>DeriveFunctor</pre></li>
--   <li><pre>DeriveTraversable</pre></li>
--   </ul>
--   
--   See the <a>Data.Deriving</a> module for a full list of backported
--   changes.
--   
--   Note that some recent GHC typeclasses/extensions are not covered by
--   this package:
--   
--   <ul>
--   <li><pre>DeriveDataTypeable</pre></li>
--   <li><tt>DeriveGeneric</tt>, which was introducted in GHC 7.2 for
--   deriving <tt>Generic</tt> instances, and modified in GHC 7.6 to allow
--   derivation of <tt>Generic1</tt> instances. Use
--   <tt>Generics.Deriving.TH</tt> from <tt><a>generic-deriving</a></tt> to
--   derive <tt>Generic(1)</tt> using Template Haskell.</li>
--   <li><tt>DeriveLift</tt>, which was introduced in GHC 8.0 for deriving
--   <tt>Lift</tt> instances. Use <tt>Language.Haskell.TH.Lift</tt> from
--   <tt><a>th-lift</a></tt> to derive <tt>Lift</tt> using Template
--   Haskell.</li>
--   <li>The <tt>Bifunctor</tt> typeclass, which was introduced in GHC
--   7.10, as well as the <tt>Bifoldable</tt> and <tt>Bitraversable</tt>
--   typeclasses, which were introduced in GHC 8.2. Use
--   <tt>Data.Bifunctor.TH</tt> from <tt><a>bifunctors</a></tt> to derive
--   these typeclasses using Template Haskell.</li>
--   </ul>
@package deriving-compat
@version 0.3.4


-- | Exports functions to mechanically derive <a>Show</a>, <tt>Show1</tt>,
--   and <tt>Show2</tt> instances.
module Text.Show.Deriving

-- | Generates a <a>Show</a> instance declaration for the given data type
--   or data family instance.
deriveShow :: Name -> Q [Dec]

-- | Like <a>deriveShow</a>, but takes a <a>ShowOptions</a> argument.
deriveShowOptions :: ShowOptions -> Name -> Q [Dec]

-- | Generates a lambda expression which behaves like <a>showsPrec</a>
--   (without requiring a <a>Show</a> instance).
makeShowsPrec :: Name -> Q Exp

-- | Like <a>makeShowsPrec</a>, but takes a <a>ShowOptions</a> argument.
makeShowsPrecOptions :: ShowOptions -> Name -> Q Exp

-- | Generates a lambda expression which behaves like <a>show</a> (without
--   requiring a <a>Show</a> instance).
makeShow :: Name -> Q Exp

-- | Like <a>makeShow</a>, but takes a <a>ShowOptions</a> argument.
makeShowOptions :: ShowOptions -> Name -> Q Exp

-- | Generates a lambda expression which behaves like <a>showList</a>
--   (without requiring a <a>Show</a> instance).
makeShowList :: Name -> Q Exp

-- | Like <a>makeShowList</a>, but takes a <a>ShowOptions</a> argument.
makeShowListOptions :: ShowOptions -> Name -> Q Exp

-- | Generates a <a>Show1</a> instance declaration for the given data type
--   or data family instance.
deriveShow1 :: Name -> Q [Dec]

-- | Like <a>deriveShow1</a>, but takes a <a>ShowOptions</a> argument.
deriveShow1Options :: ShowOptions -> Name -> Q [Dec]

-- | Generates a lambda expression which behaves like
--   <tt>liftShowsPrec</tt> (without requiring a <a>Show1</a> instance).
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeLiftShowsPrec :: Name -> Q Exp

-- | Like <a>makeLiftShowsPrec</a>, but takes a <a>ShowOptions</a>
--   argument.
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeLiftShowsPrecOptions :: ShowOptions -> Name -> Q Exp

-- | Generates a lambda expression which behaves like <tt>liftShowList</tt>
--   (without requiring a <a>Show</a> instance).
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeLiftShowList :: Name -> Q Exp

-- | Like <a>makeLiftShowList</a>, but takes a <a>ShowOptions</a> argument.
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeLiftShowListOptions :: ShowOptions -> Name -> Q Exp

-- | Generates a lambda expression which behaves like <tt>showsPrec1</tt>
--   (without requiring a <a>Show1</a> instance).
makeShowsPrec1 :: Name -> Q Exp

-- | Like <a>makeShowsPrec1</a>, but takes a <a>ShowOptions</a> argument.
makeShowsPrec1Options :: ShowOptions -> Name -> Q Exp

-- | Generates a <a>Show2</a> instance declaration for the given data type
--   or data family instance.
--   
--   This function is not available with <tt>transformers-0.4</tt>.
deriveShow2 :: Name -> Q [Dec]

-- | Like <a>deriveShow2</a>, but takes a <a>ShowOptions</a> argument.
--   
--   This function is not available with <tt>transformers-0.4</tt>.
deriveShow2Options :: ShowOptions -> Name -> Q [Dec]

-- | Generates a lambda expression which behaves like
--   <tt>liftShowsPrec2</tt> (without requiring a <a>Show2</a> instance).
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeLiftShowsPrec2 :: Name -> Q Exp

-- | Like <a>makeLiftShowsPrec2</a>, but takes a <a>ShowOptions</a>
--   argument.
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeLiftShowsPrec2Options :: ShowOptions -> Name -> Q Exp

-- | Generates a lambda expression which behaves like
--   <tt>liftShowList2</tt> (without requiring a <a>Show</a> instance).
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeLiftShowList2 :: Name -> Q Exp

-- | Like <a>makeLiftShowList2</a>, but takes a <a>ShowOptions</a>
--   argument.
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeLiftShowList2Options :: ShowOptions -> Name -> Q Exp

-- | Generates a lambda expression which behaves like <tt>showsPrec2</tt>
--   (without requiring a <a>Show2</a> instance).
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeShowsPrec2 :: Name -> Q Exp

-- | Like <a>makeShowsPrec2</a>, but takes a <a>ShowOptions</a> argument.
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeShowsPrec2Options :: ShowOptions -> Name -> Q Exp

-- | Options that further configure how the functions in
--   <a>Text.Show.Deriving</a> should behave.
newtype ShowOptions
ShowOptions :: Bool -> ShowOptions

-- | If <a>True</a>, the derived <a>Show</a>, <a>Show1</a>, or <a>Show2</a>
--   instance will not surround the output of showing fields of unlifted
--   types with parentheses, and the output will be suffixed with hash
--   signs (<tt>#</tt>).
[ghc8ShowBehavior] :: ShowOptions -> Bool

-- | <a>ShowOptions</a> that match the behavior of the most recent GHC
--   release.
defaultShowOptions :: ShowOptions

-- | <a>ShowOptions</a> that match the behavior of the installed version of
--   GHC.
legacyShowOptions :: ShowOptions


-- | Exports functions to mechanically derive <a>Read</a>, <tt>Read1</tt>,
--   and <tt>Read2</tt> instances.
module Text.Read.Deriving

-- | Generates a <a>Read</a> instance declaration for the given data type
--   or data family instance.
deriveRead :: Name -> Q [Dec]

-- | Like <a>deriveRead</a>, but takes a <a>ReadOptions</a> argument.
deriveReadOptions :: ReadOptions -> Name -> Q [Dec]

-- | Generates a lambda expression which behaves like <a>readsPrec</a>
--   (without requiring a <a>Read</a> instance).
makeReadsPrec :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <tt>readPrec</tt>
--   (without requiring a <a>Read</a> instance).
makeReadPrec :: Name -> Q Exp

-- | Generates a <a>Read1</a> instance declaration for the given data type
--   or data family instance.
deriveRead1 :: Name -> Q [Dec]

-- | Like <a>deriveRead1</a>, but takes a <a>ReadOptions</a> argument.
deriveRead1Options :: ReadOptions -> Name -> Q [Dec]

-- | Generates a lambda expression which behaves like
--   <tt>liftReadsPrec</tt> (without requiring a <a>Read1</a> instance).
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeLiftReadsPrec :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <tt>readsPrec1</tt>
--   (without requiring a <a>Read1</a> instance).
makeReadsPrec1 :: Name -> Q Exp

-- | Generates a <a>Read2</a> instance declaration for the given data type
--   or data family instance.
--   
--   This function is not available with <tt>transformers-0.4</tt>.
deriveRead2 :: Name -> Q [Dec]

-- | Like <a>deriveRead2</a>, but takes a <a>ReadOptions</a> argument.
--   
--   This function is not available with <tt>transformers-0.4</tt>.
deriveRead2Options :: ReadOptions -> Name -> Q [Dec]

-- | Generates a lambda expression which behaves like
--   <tt>liftReadsPrec2</tt> (without requiring a <a>Read2</a> instance).
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeLiftReadsPrec2 :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <tt>readsPrec2</tt>
--   (without requiring a <a>Read2</a> instance).
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeReadsPrec2 :: Name -> Q Exp

-- | Options that further configure how the functions in
--   <a>Text.Read.Deriving</a> should behave.
newtype ReadOptions
ReadOptions :: Bool -> ReadOptions

-- | If <a>True</a>:
--   
--   <ul>
--   <li>Derived <a>Read</a> instances will implement <tt>readPrec</tt>,
--   not <a>readsPrec</a>, and will provide a default implementation of
--   <tt>readListPrec</tt> in terms of <tt>readPrec</tt>.</li>
--   <li>If built against <tt>base-4.10</tt> or later, derived
--   'Read1'/'Read2' instances will implement
--   'liftReadPrec'/'liftReadPrec2', not 'liftReadsPrec'/'liftReadsPrec2',
--   and will provide default implementations of
--   'liftReadListPrec'/'liftReadListPrec2' in terms of
--   'liftReadPrec'/'liftReadPrec2'. If built against an earlier version of
--   <tt>base</tt>, derived 'Read1'/'Read2' instances are not affected, so
--   they will act as if this flag were <a>False</a>.</li>
--   </ul>
--   
--   If <a>False</a>:
--   
--   <ul>
--   <li>Derived <a>Read</a> instances will implement
--   <a>readsPrec</a>.</li>
--   <li>Derived <a>Read1</a> instances will implement <tt>readsPrec1</tt>
--   (if built against <tt>transformers-0.4</tt>) or <tt>liftReadsPrec</tt>
--   (otherwise). If not built against <tt>transformers-0.4</tt>, derived
--   <a>Read2</a> instances will implement <tt>liftReadsPrec2</tt>.</li>
--   </ul>
--   
--   It's generally a good idea to enable this option, since
--   <tt>readPrec</tt> and friends are more efficient than <a>readsPrec</a>
--   and friends, since the former use the efficient <tt>ReadPrec</tt>
--   parser datatype while the latter use the slower, list-based
--   <a>ReadS</a> type.
[useReadPrec] :: ReadOptions -> Bool

-- | <a>ReadOptions</a> that favor <tt>readPrec</tt> over <a>readsPrec</a>.
defaultReadOptions :: ReadOptions


-- | Exports functions to mechanically derive <a>Traversable</a> instances
--   in a way that mimics how the <tt>-XDeriveTraversable</tt> extension
--   works since GHC 8.0.
--   
--   Derived <a>Traversable</a> instances from this module do not generate
--   superfluous <a>pure</a> expressions in its implementation of
--   <a>traverse</a>. One can verify this by compiling a module that uses
--   <a>deriveTraversable</a> with the <tt>-ddump-splices</tt> GHC flag.
--   
--   These changes make it possible to derive <tt>Traversable</tt>
--   instances for data types with unlifted argument types, e.g.,
--   
--   <pre>
--   data IntHash a = IntHash Int# a
--   
--   deriving instance Traversable IntHash -- On GHC 8.0  on later
--   $(deriveTraversable ''IntHash)        -- On GHC 7.10 and earlier
--   </pre>
--   
--   For more info on these changes, see <a>this GHC wiki page</a>.
module Data.Traversable.Deriving

-- | Generates a <a>Traversable</a> instance declaration for the given data
--   type or data family instance.
deriveTraversable :: Name -> Q [Dec]

-- | Generates a lambda expression which behaves like <a>traverse</a>
--   (without requiring a <a>Traversable</a> instance).
makeTraverse :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <a>sequenceA</a>
--   (without requiring a <a>Traversable</a> instance).
makeSequenceA :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <a>mapM</a> (without
--   requiring a <a>Traversable</a> instance).
makeMapM :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <a>sequence</a>
--   (without requiring a <a>Traversable</a> instance).
makeSequence :: Name -> Q Exp


-- | Exports functions to mechanically derive <a>Ord</a>, <tt>Ord1</tt>,
--   and <tt>Ord2</tt> instances.
module Data.Ord.Deriving

-- | Generates an <a>Ord</a> instance declaration for the given data type
--   or data family instance.
deriveOrd :: Name -> Q [Dec]

-- | Generates a lambda expression which behaves like <a>compare</a>
--   (without requiring an <a>Ord</a> instance).
makeCompare :: Name -> Q Exp

-- | Generates a lambda expression which behaves like '(&lt;)' (without
--   requiring an <a>Ord</a> instance).
makeLT :: Name -> Q Exp

-- | Generates a lambda expression which behaves like '(&lt;=)' (without
--   requiring an <a>Ord</a> instance).
makeLE :: Name -> Q Exp

-- | Generates a lambda expression which behaves like '(&gt;)' (without
--   requiring an <a>Ord</a> instance).
makeGT :: Name -> Q Exp

-- | Generates a lambda expression which behaves like '(&gt;=)' (without
--   requiring an <a>Ord</a> instance).
makeGE :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <a>max</a> (without
--   requiring an <a>Ord</a> instance).
makeMax :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <a>min</a> (without
--   requiring an <a>Ord</a> instance).
makeMin :: Name -> Q Exp

-- | Generates an <a>Ord1</a> instance declaration for the given data type
--   or data family instance.
deriveOrd1 :: Name -> Q [Dec]

-- | Generates a lambda expression which behaves like <tt>liftCompare</tt>
--   (without requiring an <a>Ord1</a> instance).
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeLiftCompare :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <tt>compare1</tt>
--   (without requiring an <a>Ord1</a> instance).
makeCompare1 :: Name -> Q Exp

-- | Generates an <a>Ord2</a> instance declaration for the given data type
--   or data family instance.
--   
--   This function is not available with <tt>transformers-0.4</tt>.
deriveOrd2 :: Name -> Q [Dec]

-- | Generates a lambda expression which behaves like <tt>liftCompare2</tt>
--   (without requiring an <a>Ord2</a> instance).
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeLiftCompare2 :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <tt>compare2</tt>
--   (without requiring an <a>Ord2</a> instance).
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeCompare2 :: Name -> Q Exp


-- | Exports functions to mechanically derive <tt>Ix</tt> instances.
module Data.Ix.Deriving

-- | Generates a <tt>Ix</tt> instance declaration for the given data type
--   or data family instance.
deriveIx :: Name -> Q [Dec]

-- | Generates a lambda expression which behaves like <tt>range</tt>
--   (without requiring an <tt>Ix</tt> instance).
makeRange :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <tt>unsafeIndex</tt>
--   (without requiring an <tt>Ix</tt> instance).
makeUnsafeIndex :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <tt>inRange</tt>
--   (without requiring an <tt>Ix</tt> instance).
makeInRange :: Name -> Q Exp


-- | Exports functions to mechanically derive <a>Functor</a> instances.
--   
--   For more info on how deriving <tt>Functor</tt> works, see <a>this GHC
--   wiki page</a>.
module Data.Functor.Deriving

-- | Generates a <a>Functor</a> instance declaration for the given data
--   type or data family instance.
deriveFunctor :: Name -> Q [Dec]

-- | Generates a lambda expression which behaves like <a>fmap</a> (without
--   requiring a <a>Functor</a> instance).
makeFmap :: Name -> Q Exp


-- | Exports functions to mechanically derive <a>Foldable</a> instances in
--   a way that mimics how the <tt>-XDeriveFoldable</tt> extension works
--   since GHC 8.0.
--   
--   These changes make it possible to derive <tt>Foldable</tt> instances
--   for data types with existential constraints, e.g.,
--   
--   <pre>
--   data WrappedSet a where
--       WrapSet :: Ord a =&gt; a -&gt; WrappedSet a
--   
--   deriving instance Foldable WrappedSet -- On GHC 8.0  on later
--   $(deriveFoldable ''WrappedSet)        -- On GHC 7.10 and earlier
--   </pre>
--   
--   In addition, derived <a>Foldable</a> instances from this module do not
--   generate superfluous <a>mempty</a> expressions in its implementation
--   of <a>foldMap</a>. One can verify this by compiling a module that uses
--   <a>deriveFoldable</a> with the <tt>-ddump-splices</tt> GHC flag.
--   
--   For more info on these changes, see <a>this GHC wiki page</a>.
module Data.Foldable.Deriving

-- | Generates a <a>Foldable</a> instance declaration for the given data
--   type or data family instance.
deriveFoldable :: Name -> Q [Dec]

-- | Generates a lambda expression which behaves like <a>foldMap</a>
--   (without requiring a <a>Foldable</a> instance).
makeFoldMap :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <a>foldr</a> (without
--   requiring a <a>Foldable</a> instance).
makeFoldr :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <tt>fold</tt>
--   (without requiring a <a>Foldable</a> instance).
makeFold :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <a>foldl</a> (without
--   requiring a <a>Foldable</a> instance).
makeFoldl :: Name -> Q Exp


-- | Exports functions to mechanically derive <a>Eq</a>, <tt>Eq1</tt>, and
--   <tt>Eq2</tt> instances.
module Data.Eq.Deriving

-- | Generates an <a>Eq</a> instance declaration for the given data type or
--   data family instance.
deriveEq :: Name -> Q [Dec]

-- | Generates a lambda expression which behaves like '(==)' (without
--   requiring an <a>Eq</a> instance).
makeEq :: Name -> Q Exp

-- | Generates a lambda expression which behaves like '(/=)' (without
--   requiring an <a>Eq</a> instance).
makeNotEq :: Name -> Q Exp

-- | Generates an <a>Eq1</a> instance declaration for the given data type
--   or data family instance.
deriveEq1 :: Name -> Q [Dec]

-- | Generates a lambda expression which behaves like <tt>liftEq</tt>
--   (without requiring an <a>Eq1</a> instance).
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeLiftEq :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <tt>eq1</tt> (without
--   requiring an <a>Eq1</a> instance).
makeEq1 :: Name -> Q Exp

-- | Generates an <a>Eq2</a> instance declaration for the given data type
--   or data family instance.
--   
--   This function is not available with <tt>transformers-0.4</tt>.
deriveEq2 :: Name -> Q [Dec]

-- | Generates a lambda expression which behaves like <tt>liftEq2</tt>
--   (without requiring an <a>Eq2</a> instance).
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeLiftEq2 :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <tt>eq2</tt> (without
--   requiring an <a>Eq2</a> instance).
--   
--   This function is not available with <tt>transformers-0.4</tt>.
makeEq2 :: Name -> Q Exp


-- | Exports functions to mechanically derive <a>Enum</a> instances.
module Data.Enum.Deriving

-- | Generates an <a>Enum</a> instance declaration for the given data type
--   or data family instance.
deriveEnum :: Name -> Q [Dec]

-- | Generates a lambda expression which behaves like <a>succ</a> (without
--   requiring an <a>Enum</a> instance).
makeSucc :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <a>pred</a> (without
--   requiring an <a>Enum</a> instance).
makePred :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <a>toEnum</a>
--   (without requiring an <a>Enum</a> instance).
makeToEnum :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <a>fromEnum</a>
--   (without requiring an <a>Enum</a> instance).
makeFromEnum :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <a>enumFrom</a>
--   (without requiring an <a>Enum</a> instance).
makeEnumFrom :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <a>enumFromThen</a>
--   (without requiring an <a>Enum</a> instance).
makeEnumFromThen :: Name -> Q Exp


-- | Exports functions to mechanically derive <a>Bounded</a> instances.
module Data.Bounded.Deriving

-- | Generates a <a>Bounded</a> instance declaration for the given data
--   type or data family instance.
deriveBounded :: Name -> Q [Dec]

-- | Generates a lambda expression which behaves like <a>minBound</a>
--   (without requiring a <a>Bounded</a> instance).
makeMinBound :: Name -> Q Exp

-- | Generates a lambda expression which behaves like <a>maxBound</a>
--   (without requiring a <a>Bounded</a> instance).
makeMaxBound :: Name -> Q Exp


-- | This module reexports all of the functionality of the other modules in
--   this library. It also provides a high-level tutorial on
--   <tt>deriving-compat</tt>'s naming conventions and best practices.
--   Typeclass-specific information can be found in their respective
--   modules.
module Data.Deriving