| Safe Haskell | Safe-Inferred |
|---|---|
| Language | GHC2021 |
Plutarch.Internal.Lift
Synopsis
- class PlutusType a => PLiftable (a :: S -> Type) where
- type AsHaskell a :: Type
- type PlutusRepr a :: Type
- haskToRepr :: AsHaskell a -> PlutusRepr a
- reprToHask :: PlutusRepr a -> Either LiftError (AsHaskell a)
- reprToPlut :: forall (s :: S). PlutusRepr a -> PLifted s a
- plutToRepr :: (forall (s :: S). PLifted s a) -> Either LiftError (PlutusRepr a)
- data LiftError
- = CouldNotEvaluate EvalError
- | TypeError BuiltinError
- | CouldNotCompile Text
- | CouldNotDecodeData
- | OtherLiftError Text
- pconstant :: forall (a :: S -> Type) (s :: S). PLiftable a => AsHaskell a -> Term s a
- plift :: forall (a :: S -> Type). PLiftable a => (forall (s :: S). Term s a) -> AsHaskell a
- newtype DeriveBuiltinPLiftable (a :: S -> Type) (h :: Type) (s :: S) = DeriveBuiltinPLiftable (a s)
- newtype DeriveDataPLiftable (a :: S -> Type) (h :: Type) (s :: S) = DeriveDataPLiftable (a s)
- newtype DeriveNewtypePLiftable (wrapper :: S -> Type) (h :: Type) (s :: S) = DeriveNewtypePLiftable (wrapper s)
- unsafeHaskToUni :: forall (h :: Type) (a :: S -> Type) (s :: S). DefaultUni `Includes` h => h -> PLifted s a
- reprToPlutUni :: forall (a :: S -> Type) (s :: S). (PLiftable a, DefaultUni `Includes` PlutusRepr a) => PlutusRepr a -> PLifted s a
- plutToReprUni :: forall (a :: S -> Type). (PLiftable a, DefaultUni `Includes` PlutusRepr a) => (forall (s :: S). PLifted s a) -> Either LiftError (PlutusRepr a)
- newtype PLifted (s :: S) (a :: S -> Type) = PLifted (Term s POpaque)
- mkPLifted :: Term s a -> PLifted s a
- getPLifted :: PLifted s a -> Term s a
- newtype PLiftedClosed (a :: S -> Type) = PLiftedClosed {
- unPLiftedClosed :: forall (s :: S). Term s POpaque
- getPLiftedClosed :: forall (a :: S -> Type). PLiftedClosed a -> forall (s :: S). Term s a
- mkPLiftedClosed :: forall (a :: S -> Type). (forall (s :: S). Term s a) -> PLiftedClosed a
- pliftedToClosed :: forall (a :: S -> Type). (forall (s :: S). PLifted s a) -> PLiftedClosed a
- pliftedFromClosed :: forall (a :: S -> Type) (s :: S). PLiftedClosed a -> PLifted s a
- punsafeCoercePLifted :: PLifted s a -> PLifted s b
Type class
class PlutusType a => PLiftable (a :: S -> Type) where Source #
Indicates that the given Plutarch type has an equivalent in Haskell (and Plutus by extension), and we have the ability to move between them.
Important note
Calling methods of PLiftable directly should rarely, if ever, be a
thing you do, unless defining your own instances without via-deriving
helpers (below). Prefer using pconstant and plift, as these handle
some of the oddities required without you having to think about them.
You should rarely, if ever, need to define PLiftable instances by hand.
Whenever possible, prefer using DeriveBuiltinPLiftable,
DeriveDataPLiftable, and DeriveNewtypePLiftable as they have fewer
complexities and caveats. See their documentation for when to use them.
If you do want to define the methods yourself, there's a few key factors to keep in mind:
- You still shouldn't write every method by hand, there are helpers
plutToReprUniandreprToPlutUnito cover common cases. - If defining
plutToReprandreprToPlutfor Scott encoded types you need to setPlutusReprPMyType =PLiftedClosedPMyType - When choosing a type for
AsHaskell, any value of that type must be representable in Plutarch. If you have internal invariants to maintain on the Haskell side, make sure you do so with great care.
Laws
Any derivations via DeriveBuiltinPLiftable, DeriveDataPLiftable, and
DeriveNewtypePLiftable automatically follow these laws.
Together, these imply plift . pconstant = id.
Since: 1.10.0
Methods
haskToRepr :: AsHaskell a -> PlutusRepr a Source #
Transform a's Haskell equivalent to its Plutus universe
representation.
reprToHask :: PlutusRepr a -> Either LiftError (AsHaskell a) Source #
Given a's Plutus universe representation, turn it back into its (true)
Haskell equivalent if possible.
reprToPlut :: forall (s :: S). PlutusRepr a -> PLifted s a Source #
Given a's Plutus universe representation, lift it into Plutarch.
plutToRepr :: (forall (s :: S). PLifted s a) -> Either LiftError (PlutusRepr a) Source #
Given a closed Plutarch term, evaluate it back into its Plutus universe representation, or fail.
Instances
Error type
Used with fromPlutarch methods to give additional information about why
evaluating a Plutarch term into a Haskell value went wrong.
Since: 1.10.0
Constructors
| CouldNotEvaluate EvalError | Evaluation failed for some reason. |
| TypeError BuiltinError | We tried to use a builtin not part of the Plutus universe. |
| CouldNotCompile Text | Compiling the term into a script failed. |
| CouldNotDecodeData |
|
| OtherLiftError Text | Something else went wrong. |
Functions
pconstant :: forall (a :: S -> Type) (s :: S). PLiftable a => AsHaskell a -> Term s a Source #
Given a Haskell-level representation of a Plutarch term, transform it into its equivalent term.
Since: 1.10.0
plift :: forall (a :: S -> Type). PLiftable a => (forall (s :: S). Term s a) -> AsHaskell a Source #
Given a closed Plutarch term, compile and evaluate it, then produce the
corresponding Haskell value. If compilation or evaluation fails somehow, this
will call error: if you need to 'trap' these outcomes and handle them
differently somehow, use reprToPlut and reprToHask manually.
Since: 1.10.0
Derivation
Via-helpers
newtype DeriveBuiltinPLiftable (a :: S -> Type) (h :: Type) (s :: S) Source #
via-deriving helper, indicating that a has a Haskell-level equivalent
h that is directly part of the Plutus default universe (instead of by way
of an encoding).
Since: 1.10.0
Constructors
| DeriveBuiltinPLiftable (a s) |
Instances
newtype DeriveDataPLiftable (a :: S -> Type) (h :: Type) (s :: S) Source #
via-deriving helper, indicating that a has a Haskell-level equivalent
h by way of its Data encoding, rather than by h being directly part of
the Plutus default universe.
Since: 1.10.0
Constructors
| DeriveDataPLiftable (a s) |
Instances
newtype DeriveNewtypePLiftable (wrapper :: S -> Type) (h :: Type) (s :: S) Source #
via-deriving helper, indicating that wrapper has a Haskell-level equivalent
h by way PInner wrapper, up to coercibility.
Since: 1.10.0
Constructors
| DeriveNewtypePLiftable (wrapper s) |
Instances
Manual instance helpers
unsafeHaskToUni :: forall (h :: Type) (a :: S -> Type) (s :: S). DefaultUni `Includes` h => h -> PLifted s a Source #
Helper that bypasses PlutusRepr and lifts the Haskell equivalent
directly. This is unsafe: we cannot verify (in general) that h can be
represented sensibly as an a, so use this with care.
Since: 1.10.0
reprToPlutUni :: forall (a :: S -> Type) (s :: S). (PLiftable a, DefaultUni `Includes` PlutusRepr a) => PlutusRepr a -> PLifted s a Source #
Valid definition of reprToPlut if PlutusRepr a is in the Plutus universe.
Since: 1.10.0
plutToReprUni :: forall (a :: S -> Type). (PLiftable a, DefaultUni `Includes` PlutusRepr a) => (forall (s :: S). PLifted s a) -> Either LiftError (PlutusRepr a) Source #
Valid definition of plutToRepr if PlutusRepr a is in the Plutus
universe.
Since: 1.10.0
newtype PLifted (s :: S) (a :: S -> Type) Source #
Similar to Identity, but at the level of Plutarch. Only needed when
writing manual instances of PLiftable, or if you want to use reprToPlut
and plutToRepr directly.
This is used for coercing Plutarch terms at Haskell level with
`coerce :: PLifted s a -> PLifted s b` for via-deriving helpers.
Since: 1.10.0
getPLifted :: PLifted s a -> Term s a Source #
Since: 1.10.0
newtype PLiftedClosed (a :: S -> Type) Source #
Use this as PlutusRepr when defining PLiftable instances for Scott encoded types.
Since: 1.10.0
Constructors
| PLiftedClosed | |
Fields
| |
getPLiftedClosed :: forall (a :: S -> Type). PLiftedClosed a -> forall (s :: S). Term s a Source #
Since: 1.10.0
mkPLiftedClosed :: forall (a :: S -> Type). (forall (s :: S). Term s a) -> PLiftedClosed a Source #
Since: 1.10.0
pliftedToClosed :: forall (a :: S -> Type). (forall (s :: S). PLifted s a) -> PLiftedClosed a Source #
Since: 1.10.0
pliftedFromClosed :: forall (a :: S -> Type) (s :: S). PLiftedClosed a -> PLifted s a Source #
Since: 1.10.0
punsafeCoercePLifted :: PLifted s a -> PLifted s b Source #
Since: 1.10.0