lorentz-0.7.0: EDSL for the Michelson Language
Safe HaskellNone
LanguageHaskell2010

Lorentz.Errors

Synopsis

Haskell to Value conversion

class (Typeable e, ErrorHasDoc e) => IsError e where Source #

Haskell type representing error.

Methods

errorToVal :: e -> (forall t. ErrorScope t => Value t -> r) -> r Source #

Converts a Haskell error into Value representation.

errorFromVal :: KnownT t => Value t -> Either Text e Source #

Converts a Value into Haskell error.

Instances

Instances details
(TypeError ('Text "Use representative error messages") :: Constraint) => IsError () Source # 
Instance details

Defined in Lorentz.Errors

Methods

errorToVal :: () -> (forall (t :: T). ErrorScope t => Value t -> r) -> r Source #

errorFromVal :: forall (t :: T). KnownT t => Value t -> Either Text () Source #

IsError MText Source #

Use this for internal errors only.

Normal error scenarios should use the mechanism of custom errors, see below.

Instance details

Defined in Lorentz.Errors

Methods

errorToVal :: MText -> (forall (t :: T). ErrorScope t => Value t -> r) -> r Source #

errorFromVal :: forall (t :: T). KnownT t => Value t -> Either Text MText Source #

IsError UnspecifiedError Source # 
Instance details

Defined in Lorentz.Errors

Methods

errorToVal :: UnspecifiedError -> (forall (t :: T). ErrorScope t => Value t -> r) -> r Source #

errorFromVal :: forall (t :: T). KnownT t => Value t -> Either Text UnspecifiedError Source #

(CustomErrorHasDoc tag, KnownError (ErrorArg tag), IsoValue (ErrorArg tag)) => IsError (CustomError tag) Source # 
Instance details

Defined in Lorentz.Errors

Methods

errorToVal :: CustomError tag -> (forall (t :: T). ErrorScope t => Value t -> r) -> r Source #

errorFromVal :: forall (t :: T). KnownT t => Value t -> Either Text (CustomError tag) Source #

(Typeable r, NiceConstant r, ErrorHasDoc (VoidResult r)) => IsError (VoidResult r) Source # 
Instance details

Defined in Lorentz.Macro

Methods

errorToVal :: VoidResult r -> (forall (t :: T). ErrorScope t => Value t -> r0) -> r0 Source #

errorFromVal :: forall (t :: T). KnownT t => Value t -> Either Text (VoidResult r) Source #

(Typeable arg, IsError (CustomError tag), TypeErrorUnless (arg == ()) notVoidError, arg ~ ErrorArg tag, notVoidError ~ ('Text "This error requires argument of type " :<>: 'ShowType (ErrorArg tag))) => IsError (arg -> CustomError tag) Source #

If CustomError constructor is not provided its argument, we assume that this is no-arg error and interpret the passed value as complete.

Instance details

Defined in Lorentz.Errors

Methods

errorToVal :: (arg -> CustomError tag) -> (forall (t :: T). ErrorScope t => Value t -> r) -> r Source #

errorFromVal :: forall (t :: T). KnownT t => Value t -> Either Text (arg -> CustomError tag) Source #

type ErrorScope t = (Typeable t, ConstantScope t) Source #

isoErrorToVal :: (KnownError e, IsoValue e) => e -> (forall t. ErrorScope t => Value t -> r) -> r Source #

Implementation of errorToVal via IsoValue.

isoErrorFromVal :: (Typeable t, Typeable (ToT e), IsoValue e) => Value t -> Either Text e Source #

Implementation of errorFromVal via IsoValue.

class Typeable e => ErrorHasDoc (e :: Type) where Source #

Associated Types

type ErrorRequirements e :: Constraint Source #

Constraints which we require in a particular instance. You are not oblidged to often instantiate this correctly, it is only useful for some utilities.

Methods

errorDocName :: Text Source #

Name of error as it appears in the corresponding section title.

errorDocMdCause :: Markdown Source #

What should happen for this error to be raised.

errorDocMdCauseInEntrypoint :: Markdown Source #

Brief version of errorDocMdCause.

This will appear along with the error when mentioned in entrypoint description. By default, the first sentence of the full description is used.

errorDocHaskellRep :: Markdown Source #

How this error is represented in Haskell.

errorDocClass :: ErrorClass Source #

Error class.

errorDocDependencies :: [SomeDocDefinitionItem] Source #

Which definitions documentation for this error mentions.

errorDocRequirements :: Dict (ErrorRequirements e) Source #

Captured constraints which we require in a particular instance. This is a way to encode a bidirectional instance in the nowaday Haskell, for class MyConstraint => ErrorHasDoc MyType instance it lets deducing MyConstraint by ErrorHasDoc MyType.

You are not oblidged to always instantiate, it is only useful for some utilities which otherwise would not compile.

Instances

Instances details
(TypeError ('Text "Use representative error messages") :: Constraint) => ErrorHasDoc () Source # 
Instance details

Defined in Lorentz.Errors

Associated Types

type ErrorRequirements () Source #

ErrorHasDoc MText Source # 
Instance details

Defined in Lorentz.Errors

Associated Types

type ErrorRequirements MText Source #

ErrorHasDoc UnspecifiedError Source # 
Instance details

Defined in Lorentz.Errors

(CustomErrorHasDoc tag, SingI (ToT (ErrorArg tag))) => ErrorHasDoc (CustomError tag) Source # 
Instance details

Defined in Lorentz.Errors

Associated Types

type ErrorRequirements (CustomError tag) Source #

TypeHasDoc r => ErrorHasDoc (VoidResult r) Source # 
Instance details

Defined in Lorentz.Macro

Associated Types

type ErrorRequirements (VoidResult r) Source #

(Typeable arg, ErrorHasDoc (CustomError tag)) => ErrorHasDoc (arg -> CustomError tag) Source # 
Instance details

Defined in Lorentz.Errors

Associated Types

type ErrorRequirements (arg -> CustomError tag) Source #

(ErrorHasDoc err, KnownNat numTag, ErrorHasNumericDoc err) => ErrorHasDoc (NumericErrorWrapper numTag err) Source # 
Instance details

Defined in Lorentz.Errors.Numeric.Doc

Associated Types

type ErrorRequirements (NumericErrorWrapper numTag err) Source #

typeDocMdDescriptionReferToError :: forall e. IsError e => Markdown Source #

Implementation of typeDocMdDescription (of TypeHasDoc typeclass) for Haskell types which sole purpose is to be error.

customErrorDocHaskellRepGeneral :: (SingI (ToT (ErrorArg tag)), IsError (CustomError tag), TypeHasDoc (ErrorArg tag), CustomErrorHasDoc tag) => Text -> Proxy tag -> Markdown Source #

Description of error representation in Haskell.

data UnspecifiedError Source #

Use this type as replacement for () when you really want to leave error cause unspecified.

Constructors

UnspecifiedError 

Instances

Instances details
Generic UnspecifiedError Source # 
Instance details

Defined in Lorentz.Errors

Associated Types

type Rep UnspecifiedError :: Type -> Type #

IsoValue UnspecifiedError Source # 
Instance details

Defined in Lorentz.Errors

Associated Types

type ToT UnspecifiedError :: T #

ErrorHasDoc UnspecifiedError Source # 
Instance details

Defined in Lorentz.Errors

IsError UnspecifiedError Source # 
Instance details

Defined in Lorentz.Errors

Methods

errorToVal :: UnspecifiedError -> (forall (t :: T). ErrorScope t => Value t -> r) -> r Source #

errorFromVal :: forall (t :: T). KnownT t => Value t -> Either Text UnspecifiedError Source #

type Rep UnspecifiedError Source # 
Instance details

Defined in Lorentz.Errors

type Rep UnspecifiedError = D1 ('MetaData "UnspecifiedError" "Lorentz.Errors" "lorentz-0.7.0-inplace" 'False) (C1 ('MetaCons "UnspecifiedError" 'PrefixI 'False) (U1 :: Type -> Type))
type ToT UnspecifiedError Source # 
Instance details

Defined in Lorentz.Errors

type ErrorRequirements UnspecifiedError Source # 
Instance details

Defined in Lorentz.Errors

data SomeError Source #

Type wrapper for an IsError.

Constructors

forall e.(IsError e, Eq e) => SomeError e 

Instances

Instances details
Eq SomeError Source # 
Instance details

Defined in Lorentz.Errors

Show SomeError Source # 
Instance details

Defined in Lorentz.Errors

Buildable SomeError Source # 
Instance details

Defined in Lorentz.Errors

Methods

build :: SomeError -> Builder #

General instructions

failUsing :: forall e s t. IsError e => e -> s :-> t Source #

Fail with the given Haskell value.

failUnexpected :: MText -> s :-> t Source #

Fail, providing a reference to the place in the code where this function is called.

Like error in Haskell code, this instruction is for internal errors only.

Custom errors

type family ErrorArg (tag :: Symbol) :: Type Source #

Declares a custom error, defining error name - error argument relation.

If your error is supposed to carry no argument, then provide ().

Note that this relation is defined globally rather than on per-contract basis, so define errors accordingly. If your error has argument specific to your contract, call it such that error name reflects its belonging to this contract.

This is the basic [error format].

Instances

Instances details
type ErrorArg "emptySupplied" Source #

Someone constructed Empty type.

Instance details

Defined in Lorentz.Empty

type ErrorArg "emptySupplied" = ()
type ErrorArg "senderIsNotAdmin" Source #

Contract initiator should be contract admin in order to perform this operation.

Instance details

Defined in Lorentz.Errors.Common

type ErrorArg "senderIsNotAdmin" = ()
type ErrorArg "uparamArgumentUnpackFailed" Source # 
Instance details

Defined in Lorentz.UParam

type ErrorArg "uparamArgumentUnpackFailed" = ()
type ErrorArg "uparamNoSuchEntrypoint" Source # 
Instance details

Defined in Lorentz.UParam

type ErrorArg "uparamNoSuchEntrypoint" = MText

data CustomError (tag :: Symbol) Source #

Material custom error.

Use this in pattern matches against error (e.g. in tests).

Constructors

CustomError 

Fields

Instances

Instances details
Eq (ErrorArg tag) => Eq (CustomError tag) Source # 
Instance details

Defined in Lorentz.Errors

Methods

(==) :: CustomError tag -> CustomError tag -> Bool #

(/=) :: CustomError tag -> CustomError tag -> Bool #

Show (ErrorArg tag) => Show (CustomError tag) Source # 
Instance details

Defined in Lorentz.Errors

Methods

showsPrec :: Int -> CustomError tag -> ShowS #

show :: CustomError tag -> String #

showList :: [CustomError tag] -> ShowS #

Buildable (CustomError "emptySupplied") Source # 
Instance details

Defined in Lorentz.Empty

Methods

build :: CustomError "emptySupplied" -> Builder #

Buildable (CustomError "senderIsNotAdmin") Source # 
Instance details

Defined in Lorentz.Errors.Common

Methods

build :: CustomError "senderIsNotAdmin" -> Builder #

Buildable (CustomError "uparamArgumentUnpackFailed") Source # 
Instance details

Defined in Lorentz.UParam

Methods

build :: CustomError "uparamArgumentUnpackFailed" -> Builder #

Buildable (CustomError "uparamNoSuchEntrypoint") Source # 
Instance details

Defined in Lorentz.UParam

Methods

build :: CustomError "uparamNoSuchEntrypoint" -> Builder #

(WellTypedIsoValue (ErrorArg tag), TypeError ('Text "CustomError has no IsoValue instance") :: Constraint) => IsoValue (CustomError tag) Source #

This instance cannot be implemented, use IsError instance instead.

Instance details

Defined in Lorentz.Errors

Associated Types

type ToT (CustomError tag) :: T #

Methods

toVal :: CustomError tag -> Value (ToT (CustomError tag)) #

fromVal :: Value (ToT (CustomError tag)) -> CustomError tag #

(CustomErrorHasDoc tag, SingI (ToT (ErrorArg tag))) => ErrorHasDoc (CustomError tag) Source # 
Instance details

Defined in Lorentz.Errors

Associated Types

type ErrorRequirements (CustomError tag) Source #

(CustomErrorHasDoc tag, KnownError (ErrorArg tag), IsoValue (ErrorArg tag)) => IsError (CustomError tag) Source # 
Instance details

Defined in Lorentz.Errors

Methods

errorToVal :: CustomError tag -> (forall (t :: T). ErrorScope t => Value t -> r) -> r Source #

errorFromVal :: forall (t :: T). KnownT t => Value t -> Either Text (CustomError tag) Source #

Eq (ErrorArg tag) => Eq (() -> CustomError tag) Source # 
Instance details

Defined in Lorentz.Errors

Methods

(==) :: (() -> CustomError tag) -> (() -> CustomError tag) -> Bool #

(/=) :: (() -> CustomError tag) -> (() -> CustomError tag) -> Bool #

Show (ErrorArg tag) => Show (() -> CustomError tag) Source # 
Instance details

Defined in Lorentz.Errors

Methods

showsPrec :: Int -> (() -> CustomError tag) -> ShowS #

show :: (() -> CustomError tag) -> String #

showList :: [() -> CustomError tag] -> ShowS #

(Typeable arg, ErrorHasDoc (CustomError tag)) => ErrorHasDoc (arg -> CustomError tag) Source # 
Instance details

Defined in Lorentz.Errors

Associated Types

type ErrorRequirements (arg -> CustomError tag) Source #

(Typeable arg, IsError (CustomError tag), TypeErrorUnless (arg == ()) notVoidError, arg ~ ErrorArg tag, notVoidError ~ ('Text "This error requires argument of type " :<>: 'ShowType (ErrorArg tag))) => IsError (arg -> CustomError tag) Source #

If CustomError constructor is not provided its argument, we assume that this is no-arg error and interpret the passed value as complete.

Instance details

Defined in Lorentz.Errors

Methods

errorToVal :: (arg -> CustomError tag) -> (forall (t :: T). ErrorScope t => Value t -> r) -> r Source #

errorFromVal :: forall (t :: T). KnownT t => Value t -> Either Text (arg -> CustomError tag) Source #

type ToT (CustomError tag) Source # 
Instance details

Defined in Lorentz.Errors

type ToT (CustomError tag) = ToT (MText, ErrorArg tag)
type ErrorRequirements (CustomError tag) Source # 
Instance details

Defined in Lorentz.Errors

type ErrorRequirements (arg -> CustomError tag) Source # 
Instance details

Defined in Lorentz.Errors

type ErrorRequirements (arg -> CustomError tag) = ()

failCustom :: forall tag err s any. (err ~ ErrorArg tag, CustomErrorHasDoc tag, KnownError err) => Label tag -> (err ': s) :-> any Source #

Fail with given custom error.

type RequireNoArgError tag msg = (TypeErrorUnless (ErrorArg tag == ()) msg, msg ~ ('Text "Expected no-arg error, but given error requires argument of type " :<>: 'ShowType (ErrorArg tag))) Source #

failCustom_ :: forall tag s any notVoidErrorMsg. (RequireNoArgError tag notVoidErrorMsg, CustomErrorHasDoc tag) => Label tag -> s :-> any Source #

Specialization of failCustom for no-arg errors.

Documentation

data ErrorClass Source #

Error class on how the error should be handled by the client.

Constructors

ErrClassActionException

Normal expected error. Examples: "insufficient balance", "wallet does not exist".

ErrClassBadArgument

Invalid argument passed to entrypoint. Examples: your entrypoint accepts an enum represented as nat, and unknown value is provided. This includes more complex cases which involve multiple entrypoints. E.g. API provides iterator interface, middleware should care about using it hiding complex details and exposing a simpler API to user; then an attempt to request non-existing element would also correspond to an error from this class.

ErrClassContractInternal

Unexpected error. Most likely it means that there is a bug in the contract or the contract has been deployed incorrectly.

ErrClassUnknown

It's possible to leave error class unspecified.

Instances

Instances details
Read ErrorClass Source # 
Instance details

Defined in Lorentz.Errors

Lift ErrorClass Source # 
Instance details

Defined in Lorentz.Errors

Methods

lift :: ErrorClass -> Q Exp #

Buildable ErrorClass Source # 
Instance details

Defined in Lorentz.Errors

Methods

build :: ErrorClass -> Builder #

class (KnownSymbol tag, TypeHasDoc (ErrorArg tag), IsError (CustomError tag)) => CustomErrorHasDoc tag where Source #

Minimal complete definition

customErrDocMdCause, customErrClass

Methods

customErrDocMdCause :: Markdown Source #

What should happen for this error to be raised.

customErrDocMdCauseInEntrypoint :: Markdown Source #

Brief version of customErrDocMdCause. This will appear along with the error when mentioned in entrypoint description.

By default, the first sentence of the full description is used.

customErrClass :: ErrorClass Source #

Error class.

By default this returns "unknown error" class; though you should provide explicit implementation in order to avoid a warning.

customErrArgumentSemantics :: Maybe Markdown Source #

Clarification of error argument meaning.

Provide when it's not obvious, e.g. argument is not named with :!.

NOTE: This should not be an entire sentence, rather just the semantic backbone.

Bad: * Error argument stands for the previous value of approval.

Good: * the previous value of approval * pair, first argument of which is one thing, and the second is another

data DError where Source #

Mentions that contract uses given error.

Constructors

DError :: ErrorHasDoc e => Proxy e -> DError 

data DThrows where Source #

Documentation for custom errors.

Mentions that entrypoint throws given error.

Constructors

DThrows :: ErrorHasDoc e => Proxy e -> DThrows 

Internals

errorTagToText :: forall tag. KnownSymbol tag => Text Source #

errorTagToMText :: Label tag -> MText Source #

Demote error tag to term level.