deriving-compat-0.6.7: Backports of GHC deriving extensions

Copyright | (C) 2015-2017 Ryan Scott
License | BSD-style (see the file LICENSE)
Maintainer | Ryan Scott
Portability | Template Haskell
Safe Haskell | None
Language | Haskell2010

Text.Read.Deriving

Contents

- `Read`
- `Read1`
- `Read2`
- `ReadOptions`
- `deriveRead` limitations

Description

Exports functions to mechanically derive `Read`, `Read1`, and `Read2` instances. Note that upstream GHC does not have the ability to derive `Read1` or `Read2` instances, but since the functionality to derive `Read` extends very naturally `Read1` and `Read2`, the ability to derive the latter two classes is provided as a convenience.

Synopsis

- deriveRead :: Name -> Q [Dec]
- deriveReadOptions :: ReadOptions -> Name -> Q [Dec]
- makeReadsPrec :: Name -> Q Exp
- makeReadPrec :: Name -> Q Exp
- deriveRead1 :: Name -> Q [Dec]
- deriveRead1Options :: ReadOptions -> Name -> Q [Dec]
- makeLiftReadsPrec :: Name -> Q Exp
- makeLiftReadPrec :: Name -> Q Exp
- makeReadPrec1 :: Name -> Q Exp
- makeReadsPrec1 :: Name -> Q Exp
- deriveRead2 :: Name -> Q [Dec]
- deriveRead2Options :: ReadOptions -> Name -> Q [Dec]
- makeLiftReadsPrec2 :: Name -> Q Exp
- makeLiftReadPrec2 :: Name -> Q Exp
- makeReadPrec2 :: Name -> Q Exp
- makeReadsPrec2 :: Name -> Q Exp
- newtype ReadOptions = ReadOptions {
  - useReadPrec :: Bool
  }
- defaultReadOptions :: ReadOptions

# `Read`

deriveRead :: Name -> Q [Dec] Source #

Generates a `Read` instance declaration for the given data type or data family instance.

deriveReadOptions :: ReadOptions -> Name -> Q [Dec] Source #

Like `deriveRead`, but takes a `ReadOptions` argument.

makeReadsPrec :: Name -> Q Exp Source #

Generates a lambda expression which behaves like `readsPrec` (without requiring a `Read` instance).

makeReadPrec :: Name -> Q Exp Source #

Generates a lambda expression which behaves like `readPrec` (without requiring a `Read` instance).

# `Read1`

deriveRead1 :: Name -> Q [Dec] Source #

Generates a `Read1` instance declaration for the given data type or data family instance.

deriveRead1Options :: ReadOptions -> Name -> Q [Dec] Source #

Like `deriveRead1`, but takes a `ReadOptions` argument.

makeLiftReadsPrec :: Name -> Q Exp Source #

Generates a lambda expression which behaves like `liftReadsPrec` (without requiring a `Read1` instance).

This function is not available with `transformers-0.4`.

makeLiftReadPrec :: Name -> Q Exp Source #

Generates a lambda expression which behaves like `liftReadPrec` (without requiring a `Read1` instance).

This function is only available with `base-4.10` or later.

makeReadPrec1 :: Name -> Q Exp Source #

Generates a lambda expression which behaves like `readPrec1` (without requiring a `Read1` instance).

This function is only available with `base-4.10` or later.

makeReadsPrec1 :: Name -> Q Exp Source #

Generates a lambda expression which behaves like `readsPrec1` (without requiring a `Read1` instance).

# `Read2`

deriveRead2 :: Name -> Q [Dec] Source #

Generates a `Read2` instance declaration for the given data type or data family instance.

This function is not available with `transformers-0.4`.

deriveRead2Options :: ReadOptions -> Name -> Q [Dec] Source #

Like `deriveRead2`, but takes a `ReadOptions` argument.

This function is not available with `transformers-0.4`.

makeLiftReadsPrec2 :: Name -> Q Exp Source #

Generates a lambda expression which behaves like `liftReadsPrec2` (without requiring a `Read2` instance).

This function is not available with `transformers-0.4`.

makeLiftReadPrec2 :: Name -> Q Exp Source #

Generates a lambda expression which behaves like `liftReadPrec2` (without requiring a `Read2` instance).

This function is only available with `base-4.10` or later.

makeReadPrec2 :: Name -> Q Exp Source #

Generates a lambda expression which behaves like `readPrec2` (without requiring a `Read2` instance).

This function is only available with `base-4.10` or later.

makeReadsPrec2 :: Name -> Q Exp Source #

Generates a lambda expression which behaves like `readsPrec2` (without requiring a `Read2` instance).

This function is not available with `transformers-0.4`.

# `ReadOptions`

newtype ReadOptions Source #

Options that further configure how the functions in Text.Read.Deriving should behave.

Constructors

ReadOptions |

Fields

- useReadPrec :: Bool

  If `True`:

  - Derived `Read` instances will implement `readPrec`, not `readsPrec`, and will provide a default implementation of `readListPrec` in terms of `readPrec`.
  - If built against `base-4.10` 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 `base`, derived `Read1`/`Read2` instances are not affected, so they will act as if this flag were `False`.

  If `False`:

  - Derived `Read` instances will implement `readsPrec`.
  - Derived `Read1` instances will implement `readsPrec1` (if built against `transformers-0.4`) or `liftReadsPrec` (otherwise). If not built against `transformers-0.4`, derived `Read2` instances will implement `liftReadsPrec2`.

  It's generally a good idea to enable this option, since `readPrec` and friends are more efficient than `readsPrec` and friends, since the former use the efficient `ReadPrec` parser datatype while the latter use the slower, list-based `ReadS` type.

#### Instances

Instances details

Read ReadOptions Source # |
Instance details Defined in Text.Read.Deriving.Internal Methods readsPrec :: Int -> ReadS ReadOptions Source # readList :: ReadS [ReadOptions] Source # readPrec :: ReadPrec ReadOptions Source # readListPrec :: ReadPrec [ReadOptions] Source #
Show ReadOptions Source # |
Instance details Defined in Text.Read.Deriving.Internal Methods showsPrec :: Int -> ReadOptions -> ShowS Source # show :: ReadOptions -> String Source # showList :: [ReadOptions] -> ShowS Source #
Eq ReadOptions Source # |
Instance details Defined in Text.Read.Deriving.Internal Methods (==) :: ReadOptions -> ReadOptions -> Bool Source # (/=) :: ReadOptions -> ReadOptions -> Bool Source #
Ord ReadOptions Source # |

Instance details

Defined in Text.Read.Deriving.Internal

Methods

compare :: ReadOptions -> ReadOptions -> Ordering Source #

(<) :: ReadOptions -> ReadOptions -> Bool Source #

(<=) :: ReadOptions -> ReadOptions -> Bool Source #

(>) :: ReadOptions -> ReadOptions -> Bool Source #

(>=) :: ReadOptions -> ReadOptions -> Bool Source #

max :: ReadOptions -> ReadOptions -> ReadOptions Source #

min :: ReadOptions -> ReadOptions -> ReadOptions Source #

defaultReadOptions :: ReadOptions Source #

`ReadOptions` that favor `readPrec` over `readsPrec`.

# `deriveRead` limitations

Be aware of the following potential gotchas:

- Type variables of kind `*` are assumed to have `Read` constraints. Type variables of kind `* -> *` are assumed to have `Read1` constraints. Type variables of kind `* -> * -> *` are assumed to have `Read2` constraints. If this is not desirable, use `makeReadsPrec` or one of its cousins.
- The `Read1` class had a different definition in `transformers-0.4`, and as a result, `deriveRead1` implements different instances for the `transformers-0.4` `Read1` than it otherwise does. Also, `makeLiftReadsPrec` and `makeLiftReadList` are not available when this library is built against `transformers-0.4`, only 'makeReadsPrec1.
- The `Read2` class is not available in `transformers-0.4`, and as a result, neither are Template Haskell functions that deal with `Read2` when this library is built against `transformers-0.4`.
- The `Read1` and `Read2` classes have new methods (`liftReadPrec`/`liftReadListPrec` and `liftReadPrec2`/`liftReadListPrec2`, respectively) that were introduced in `base-4.10`. For now, these methods are only defined when deriving `Read1`/`Read2` if built against `base-4.10` (until `transformers-compat` catches up), and the corresponding `make-` functions are also only available when built against `base-4.10`.