plutus-core-1.36.0.0: Language library for Plutus Core
Safe HaskellSafe-Inferred
LanguageHaskell2010

PlutusCore.Builtin.Result

Synopsis

Documentation

data EvaluationError structural operational Source #

The type of errors that can occur during evaluation. There are two kinds of errors:

  1. Structural ones -- these are errors that are indicative of the _structure_ of the program being wrong. For example, a free variable was encountered during evaluation, a non-function was applied to an argument or tailList was applied to a non-list.
  2. Operational ones -- these are errors that are indicative of the _logic_ of the program being wrong. For example, error was executed, tailList was applied to an empty list or evaluation ran out of gas.

On the chain both of these are just regular failures and we don't distinguish between them there: if a script fails, it fails, it doesn't matter what the reason was. However in the tests it does matter why the failure occurred: a structural error may indicate that the test was written incorrectly while an operational error may be entirely expected.

In other words, structural errors are "runtime type errors" and operational errors are regular runtime errors. Which means that evaluating an (erased) well-typed program should never produce a structural error, only an operational one. This creates a sort of "runtime type system" for UPLC and it would be great to stick to it and enforce in tests etc, but we currently don't.

Constructors

StructuralEvaluationError !structural 
OperationalEvaluationError !operational 

Instances

Instances details
Bifoldable EvaluationError Source # 
Instance details

Defined in PlutusCore.Evaluation.Error

Methods

bifoldMonoid m ⇒ EvaluationError m m → m Source #

bifoldMapMonoid m ⇒ (a → m) → (b → m) → EvaluationError a b → m Source #

bifoldr ∷ (a → c → c) → (b → c → c) → c → EvaluationError a b → c Source #

bifoldl ∷ (c → a → c) → (c → b → c) → c → EvaluationError a b → c Source #

Bifunctor EvaluationError Source # 
Instance details

Defined in PlutusCore.Evaluation.Error

Methods

bimap ∷ (a → b) → (c → d) → EvaluationError a c → EvaluationError b d Source #

first ∷ (a → b) → EvaluationError a c → EvaluationError b c Source #

second ∷ (b → c) → EvaluationError a b → EvaluationError a c Source #

Bitraversable EvaluationError Source # 
Instance details

Defined in PlutusCore.Evaluation.Error

Methods

bitraverseApplicative f ⇒ (a → f c) → (b → f d) → EvaluationError a b → f (EvaluationError c d) Source #

(HasPrettyDefaults config ~ 'True, PrettyBy config structural, Pretty operational) ⇒ PrettyBy config (EvaluationError structural operational) Source # 
Instance details

Defined in PlutusCore.Evaluation.Error

Methods

prettyBy ∷ config → EvaluationError structural operational → Doc ann Source #

prettyListBy ∷ config → [EvaluationError structural operational] → Doc ann Source #

Functor (EvaluationError structural) Source # 
Instance details

Defined in PlutusCore.Evaluation.Error

Methods

fmap ∷ (a → b) → EvaluationError structural a → EvaluationError structural b Source #

(<$) ∷ a → EvaluationError structural b → EvaluationError structural a Source #

Generic (EvaluationError structural operational) Source # 
Instance details

Defined in PlutusCore.Evaluation.Error

Associated Types

type Rep (EvaluationError structural operational) ∷ TypeType Source #

Methods

fromEvaluationError structural operational → Rep (EvaluationError structural operational) x Source #

toRep (EvaluationError structural operational) x → EvaluationError structural operational Source #

(Show structural, Show operational) ⇒ Show (EvaluationError structural operational) Source # 
Instance details

Defined in PlutusCore.Evaluation.Error

Methods

showsPrecIntEvaluationError structural operational → ShowS Source #

showEvaluationError structural operational → String Source #

showList ∷ [EvaluationError structural operational] → ShowS Source #

(NFData structural, NFData operational) ⇒ NFData (EvaluationError structural operational) Source # 
Instance details

Defined in PlutusCore.Evaluation.Error

Methods

rnfEvaluationError structural operational → () Source #

(Eq structural, Eq operational) ⇒ Eq (EvaluationError structural operational) Source # 
Instance details

Defined in PlutusCore.Evaluation.Error

Methods

(==)EvaluationError structural operational → EvaluationError structural operational → Bool Source #

(/=)EvaluationError structural operational → EvaluationError structural operational → Bool Source #

(AsUnliftingError structural, AsUnliftingError operational) ⇒ AsUnliftingEvaluationError (EvaluationError structural operational) Source #

An UnliftingEvaluationError is an EvaluationError, hence for this instance we only require both structural and operational to have _UnliftingError prisms, so that we can handle both the cases pointwisely.

Instance details

Defined in PlutusCore.Builtin.Result

AsEvaluationFailure operational ⇒ AsEvaluationFailure (EvaluationError structural operational) Source #

A raw evaluation failure is always an operational error.

Instance details

Defined in PlutusCore.Evaluation.Error

Methods

_EvaluationFailure ∷ Prism' (EvaluationError structural operational) () Source #

(Pretty structural, Pretty operational) ⇒ Pretty (EvaluationError structural operational) Source # 
Instance details

Defined in PlutusCore.Evaluation.Error

Methods

prettyEvaluationError structural operational → Doc ann Source #

prettyList ∷ [EvaluationError structural operational] → Doc ann Source #

structural ~ MachineError fun ⇒ AsMachineError (EvaluationError structural operational) fun Source # 
Instance details

Defined in PlutusCore.Evaluation.Machine.Exception

Methods

_MachineError ∷ Prism' (EvaluationError structural operational) (MachineError fun) Source #

_NonPolymorphicInstantiationMachineError ∷ Prism' (EvaluationError structural operational) () Source #

_NonWrapUnwrappedMachineError ∷ Prism' (EvaluationError structural operational) () Source #

_NonFunctionalApplicationMachineError ∷ Prism' (EvaluationError structural operational) () Source #

_OpenTermEvaluatedMachineError ∷ Prism' (EvaluationError structural operational) () Source #

_UnliftingMachineError ∷ Prism' (EvaluationError structural operational) UnliftingError Source #

_BuiltinTermArgumentExpectedMachineError ∷ Prism' (EvaluationError structural operational) () Source #

_UnexpectedBuiltinTermArgumentMachineError ∷ Prism' (EvaluationError structural operational) () Source #

_NonConstrScrutinized ∷ Prism' (EvaluationError structural operational) () Source #

_MissingCaseBranch ∷ Prism' (EvaluationError structural operational) Word64 Source #

AsEvaluationError (EvaluationError structural operational) structural operational Source # 
Instance details

Defined in PlutusCore.Evaluation.Error

Methods

_EvaluationError ∷ Prism' (EvaluationError structural operational) (EvaluationError structural operational) Source #

_StructuralEvaluationError ∷ Prism' (EvaluationError structural operational) structural Source #

_OperationalEvaluationError ∷ Prism' (EvaluationError structural operational) operational Source #

ThrowableBuiltins uni fun ⇒ MonadError (CekEvaluationException NamedDeBruijn uni fun) (CekM uni fun s) Source # 
Instance details

Defined in UntypedPlutusCore.Evaluation.Machine.Cek.Internal

Methods

throwErrorCekEvaluationException NamedDeBruijn uni fun → CekM uni fun s a Source #

catchErrorCekM uni fun s a → (CekEvaluationException NamedDeBruijn uni fun → CekM uni fun s a) → CekM uni fun s a Source #

type Rep (EvaluationError structural operational) Source # 
Instance details

Defined in PlutusCore.Evaluation.Error

type Rep (EvaluationError structural operational) = D1 ('MetaData "EvaluationError" "PlutusCore.Evaluation.Error" "plutus-core-1.36.0.0-inplace" 'False) (C1 ('MetaCons "StructuralEvaluationError" 'PrefixI 'False) (S1 ('MetaSel ('NothingMaybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 structural)) :+: C1 ('MetaCons "OperationalEvaluationError" 'PrefixI 'False) (S1 ('MetaSel ('NothingMaybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 operational)))

class AsEvaluationError r structural operational | r → structural operational where Source #

Minimal complete definition

_EvaluationError

Methods

_EvaluationError ∷ Prism' r (EvaluationError structural operational) Source #

_StructuralEvaluationError ∷ Prism' r structural Source #

_OperationalEvaluationError ∷ Prism' r operational Source #

Instances

Instances details
AsEvaluationError UnliftingEvaluationError UnliftingError UnliftingError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

AsEvaluationError (EvaluationError structural operational) structural operational Source # 
Instance details

Defined in PlutusCore.Evaluation.Error

Methods

_EvaluationError ∷ Prism' (EvaluationError structural operational) (EvaluationError structural operational) Source #

_StructuralEvaluationError ∷ Prism' (EvaluationError structural operational) structural Source #

_OperationalEvaluationError ∷ Prism' (EvaluationError structural operational) operational Source #

newtype UnliftingError Source #

The error message part of an UnliftingEvaluationError.

Constructors

MkUnliftingError 

Instances

Instances details
IsString UnliftingError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

Monoid UnliftingError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

Semigroup UnliftingError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

Show UnliftingError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

NFData UnliftingError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

Methods

rnfUnliftingError → () Source #

Eq UnliftingError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

AsUnliftingError UnliftingError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

Pretty UnliftingError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

AsEvaluationError UnliftingEvaluationError UnliftingError UnliftingError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

newtype UnliftingEvaluationError Source #

When unlifting of a PLC term into a Haskell value fails, this error is thrown.

Instances

Instances details
Show UnliftingEvaluationError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

NFData UnliftingEvaluationError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

Eq UnliftingEvaluationError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

AsUnliftingEvaluationError UnliftingEvaluationError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

Pretty UnliftingEvaluationError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

AsEvaluationError UnliftingEvaluationError UnliftingError UnliftingError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

data BuiltinError Source #

The type of errors that readKnown and makeKnown can return.

Instances

Instances details
Show BuiltinError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

Eq BuiltinError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

AsBuiltinError BuiltinError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

AsUnliftingEvaluationError BuiltinError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

AsEvaluationFailure BuiltinError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

Pretty BuiltinError Source # 
Instance details

Defined in PlutusCore.Builtin.Result

Methods

prettyBuiltinErrorDoc ann Source #

prettyList ∷ [BuiltinError] → Doc ann Source #

MonadError BuiltinError BuiltinResult Source #

throwError puts every operational unlifting error into the BuiltinFailure logs. This is to compensate for the historical lack of error message content in operational errors (structural ones don't have this problem) in our evaluators (the CK and CEK machines). It would be better to fix the underlying issue and allow operational evaluation errors to carry some form of content, but for now we just fix the symptom in order for the end user to see the error message that they are supposed to see. The fix even makes some sense: what we do here is we emulate logging when the thrown unlifting error is an operational one, i.e. this is similar to what some builtins do manually (like when a crypto builtin fails and puts info about the failure into the logs).

Instance details

Defined in PlutusCore.Builtin.Result

data BuiltinResult a Source #

The monad that makeKnown runs in. Equivalent to ExceptT BuiltinError (Writer (DList Text)), except optimized in two ways:

  1. everything is strict
  2. has the BuiltinSuccess constructor that is used for returning a value with no logs attached, which is the most common case for us, so it helps a lot not to construct and deconstruct a redundant tuple

Moving from ExceptT BuiltinError (Writer (DList Text)) to this data type gave us a speedup of 8% of total evaluation time.

Logs are represented as a DList, because we don't particularly care about the efficiency of logging, since there's no logging on the chain and builtins don't emit much anyway. Otherwise we'd have to use text-builder or text-builder-linear or something of this sort.

Instances

Instances details
MonadFail BuiltinResult Source # 
Instance details

Defined in PlutusCore.Builtin.Result

Methods

failStringBuiltinResult a Source #

Foldable BuiltinResult Source # 
Instance details

Defined in PlutusCore.Builtin.Result

Methods

foldMonoid m ⇒ BuiltinResult m → m Source #

foldMapMonoid m ⇒ (a → m) → BuiltinResult a → m Source #

foldMap'Monoid m ⇒ (a → m) → BuiltinResult a → m Source #

foldr ∷ (a → b → b) → b → BuiltinResult a → b Source #

foldr' ∷ (a → b → b) → b → BuiltinResult a → b Source #

foldl ∷ (b → a → b) → b → BuiltinResult a → b Source #

foldl' ∷ (b → a → b) → b → BuiltinResult a → b Source #

foldr1 ∷ (a → a → a) → BuiltinResult a → a Source #

foldl1 ∷ (a → a → a) → BuiltinResult a → a Source #

toListBuiltinResult a → [a] Source #

nullBuiltinResult a → Bool Source #

lengthBuiltinResult a → Int Source #

elemEq a ⇒ a → BuiltinResult a → Bool Source #

maximumOrd a ⇒ BuiltinResult a → a Source #

minimumOrd a ⇒ BuiltinResult a → a Source #

sumNum a ⇒ BuiltinResult a → a Source #

productNum a ⇒ BuiltinResult a → a Source #

Applicative BuiltinResult Source # 
Instance details

Defined in PlutusCore.Builtin.Result

Functor BuiltinResult Source # 
Instance details

Defined in PlutusCore.Builtin.Result

Methods

fmap ∷ (a → b) → BuiltinResult a → BuiltinResult b Source #

(<$) ∷ a → BuiltinResult b → BuiltinResult a Source #

Monad BuiltinResult Source # 
Instance details

Defined in PlutusCore.Builtin.Result

MonadError BuiltinError BuiltinResult Source #

throwError puts every operational unlifting error into the BuiltinFailure logs. This is to compensate for the historical lack of error message content in operational errors (structural ones don't have this problem) in our evaluators (the CK and CEK machines). It would be better to fix the underlying issue and allow operational evaluation errors to carry some form of content, but for now we just fix the symptom in order for the end user to see the error message that they are supposed to see. The fix even makes some sense: what we do here is we emulate logging when the thrown unlifting error is an operational one, i.e. this is similar to what some builtins do manually (like when a crypto builtin fails and puts info about the failure into the logs).

Instance details

Defined in PlutusCore.Builtin.Result

KnownTypeAst tyname uni a ⇒ KnownTypeAst tyname uni (BuiltinResult a ∷ Type) Source # 
Instance details

Defined in PlutusCore.Builtin.KnownTypeAst

Associated Types

type IsBuiltin uni (BuiltinResult a) ∷ Bool Source #

type ToHoles uni (BuiltinResult a) ∷ [Hole] Source #

type ToBinds uni acc (BuiltinResult a) ∷ [Some TyNameRep] Source #

Methods

typeAstType0 tyname uni () Source #

MakeKnownIn uni val a ⇒ MakeKnownIn uni val (BuiltinResult a) Source # 
Instance details

Defined in PlutusCore.Builtin.KnownType

(TypeError ('Text "\8216BuiltinResult\8217 cannot appear in the type of an argument") ∷ Constraint, uni ~ UniOf val) ⇒ ReadKnownIn uni val (BuiltinResult a) Source # 
Instance details

Defined in PlutusCore.Builtin.KnownType

Methods

readKnown ∷ val → ReadKnownM (BuiltinResult a) Source #

Show a ⇒ Show (BuiltinResult a) Source # 
Instance details

Defined in PlutusCore.Builtin.Result

AsEvaluationFailure (BuiltinResult a) Source # 
Instance details

Defined in PlutusCore.Builtin.Result

Methods

_EvaluationFailure ∷ Prism' (BuiltinResult a) () Source #

AsBuiltinResult (BuiltinResult a) a Source # 
Instance details

Defined in PlutusCore.Builtin.Result

type ToBinds uni acc (BuiltinResult a ∷ Type) Source # 
Instance details

Defined in PlutusCore.Builtin.KnownTypeAst

type ToBinds uni acc (BuiltinResult a ∷ Type) = ToBinds uni acc a
type IsBuiltin uni (BuiltinResult a ∷ Type) Source # 
Instance details

Defined in PlutusCore.Builtin.KnownTypeAst

type IsBuiltin uni (BuiltinResult a ∷ Type) = 'False
type ToHoles uni (BuiltinResult a ∷ Type) Source # 
Instance details

Defined in PlutusCore.Builtin.KnownTypeAst

type ToHoles uni (BuiltinResult a ∷ Type) = '[TypeHole a ∷ Hole]

class AsUnliftingEvaluationError r where Source #

Minimal complete definition

_UnliftingEvaluationError

class AsBuiltinResult r a | r → a where Source #

Minimal complete definition

_BuiltinResult

_UnliftingErrorViaPretty err ⇒ err → Prism' err UnliftingError Source #

Construct a prism focusing on the *EvaluationFailure part of err by taking that *EvaluationFailure and

  1. pretty-printing and embedding it into an UnliftingError for the setter part of the prism
  2. returning it directly for the opposite direction (there's no other way to convert an UnliftingError to an evaluation failure, since the latter doesn't carry any content)

This is useful for providing AsUnliftingError instances for types such as CkUserError and CekUserError.

emitTextBuiltinResult () Source #

Add a log line to the logs.

withLogsDList TextBuiltinResult a → BuiltinResult a Source #

Prepend logs to a BuiltinResult computation.

throwingMonadError e m ⇒ AReview e t → t → m x #

throwing_MonadError e m ⇒ AReview e () → m x #