| 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
- toPlutarchRepr :: AsHaskell a -> PlutusRepr a
- toPlutarch :: AsHaskell a -> PLifted s a
- fromPlutarchRepr :: PlutusRepr a -> Maybe (AsHaskell a)
- fromPlutarch :: (forall s. PLifted s a) -> Either LiftError (AsHaskell a)
- 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) (inner :: S -> Type) (h :: Type) (s :: S) = DeriveNewtypePLiftable (wrapper s)
- unsafeToUni :: forall (h :: Type) (a :: S -> Type) (s :: S). DefaultUni `Includes` h => h -> PLifted s a
- fromPlutarchUni :: forall (a :: S -> Type). (PLiftable a, DefaultUni `Includes` PlutusRepr a) => (forall s. PLifted s a) -> Either LiftError (AsHaskell a)
- toPlutarchUni :: forall (a :: S -> Type) (s :: S). (PLiftable a, DefaultUni `Includes` PlutusRepr a) => AsHaskell a -> PLifted s a
- fromPlutarchReprClosed :: forall (a :: S -> Type). (PLiftable a, PlutusRepr a ~ PLiftedClosed a) => PlutusRepr a -> Maybe (AsHaskell a)
- toPlutarchReprClosed :: forall (a :: S -> Type). (PLiftable a, PlutusRepr a ~ PLiftedClosed a) => AsHaskell a -> PlutusRepr a
- newtype PLifted s a = 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). PLifted s a
- data LiftError
- = CouldNotEvaluate EvalError
- | TypeError BuiltinError
- | CouldNotCompile Text
- | CouldNotDecodeData
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
fromPlutarch*andtoPlutarch*to cover common cases like types in Plutus universe or Scott encoding - If defining
toPlutarchReprandfromPlutarchRepryou will need to define an associatedPlutusReprtype, this is a Hasekll level type that is included in the Plutus default universe. - If defining
toPlutarchandfromPlutarchfor Scott encoded type 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
fromPlutarchRepr.toPlutarchRepr=JustfmaptoPlutarchRepr.fromPlutarchRepr=JustfromPlutarch.toPlutarch=RightfmaptoPlutarch.fromPlutarch=Right
Any derivations via DeriveBuiltinPLiftable, DeriveDataPLiftable, and
DeriveNewtypePLiftable automatically follow these laws.
@since WIP
Methods
toPlutarchRepr :: AsHaskell a -> PlutusRepr a Source #
toPlutarch :: AsHaskell a -> PLifted s a Source #
fromPlutarchRepr :: PlutusRepr a -> Maybe (AsHaskell a) Source #
fromPlutarch :: (forall s. PLifted s a) -> Either LiftError (AsHaskell a) Source #
Instances
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 WIP
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 fromPlutarch.
@since WIP
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 a Data encoding).
@since WIP
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 WIP
Constructors
| DeriveDataPLiftable (a s) |
Instances
newtype DeriveNewtypePLiftable (wrapper :: S -> Type) (inner :: S -> Type) (h :: Type) (s :: S) Source #
via-deriving helper, indicating that wrapper has a Haskell-level equivalent
h by way of encoding of inner. It requires that AsHaskell inner has the same
Haskell representation as h
@since WIP
Constructors
| DeriveNewtypePLiftable (wrapper s) |
Instances
Manual instance helpers
unsafeToUni :: forall (h :: Type) (a :: S -> Type) (s :: S). DefaultUni `Includes` h => h -> PLifted s a Source #
fromPlutarchUni :: forall (a :: S -> Type). (PLiftable a, DefaultUni `Includes` PlutusRepr a) => (forall s. PLifted s a) -> Either LiftError (AsHaskell a) Source #
Valid definition for fromPlutarch if PlutusRepr is in Plutus universe
@since WIP
toPlutarchUni :: forall (a :: S -> Type) (s :: S). (PLiftable a, DefaultUni `Includes` PlutusRepr a) => AsHaskell a -> PLifted s a Source #
Valid definition for toPlutarch if PlutusRepr is in Plutus universe
@since WIP
fromPlutarchReprClosed :: forall (a :: S -> Type). (PLiftable a, PlutusRepr a ~ PLiftedClosed a) => PlutusRepr a -> Maybe (AsHaskell a) Source #
Valid definition for fromPlutarchRepr if PlutusRepr is Scott encoded
@since WIP
toPlutarchReprClosed :: forall (a :: S -> Type). (PLiftable a, PlutusRepr a ~ PLiftedClosed a) => AsHaskell a -> PlutusRepr a Source #
Valid definition for toPlutarchRepr if PlutusRepr is Scott encoded
@since WIP
Similar to Identity, but at the level of Plutarch. Only needed when
writing manual instances of PLiftable, or if you want to use toPlutarch
and fromPlutarch directly.
This is used for coercing Plutarch terms in Haskell level with
`coerce :: PLifted s a -> PLifted s b` for via-deriving helpers
@since WIP
getPLifted :: PLifted s a -> Term s a Source #
@since WIP
newtype PLiftedClosed (a :: S -> Type) Source #
Use this as PlutusRepr when defining PLiftable instance for Scott encoded type
@since WIP
Constructors
| PLiftedClosed | |
Fields
| |
Used with fromPlutarch methods to give additional information about why
evaluating a Plutarch term into a Haskell value went wrong.
@since WIP
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 |
|