Lorentz.Errors

Haskell to Value conversion

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

Haskell type representing error.

Methods

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

Converts a Haskell error into Value representation.

errorFromVal :: (Typeable t, SingI t) => Value t -> Either Text e

Converts a Value into Haskell error.

Instances

(TypeError (Text "Use representative error messages") :: Constraint) => IsError ()

Defined in Lorentz.Errors

Methods

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

errorFromVal :: (Typeable t, SingI t) => Value t -> Either Text ()

IsError MText

Use this for internal errors only.

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

Defined in Lorentz.Errors

Methods

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

errorFromVal :: (Typeable t, SingI t) => Value t -> Either Text MText

IsError UnspecifiedError

Defined in Lorentz.Errors

Methods

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

errorFromVal :: (Typeable t, SingI t) => Value t -> Either Text UnspecifiedError

(CustomErrorHasDoc tag, KnownError (ErrorArg tag), IsoValue (ErrorArg tag)) => IsError (CustomError tag)

Defined in Lorentz.Errors

Methods

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

errorFromVal :: (Typeable t, SingI t) => Value t -> Either Text (CustomError tag)

(Typeable r, NiceConstant r, ErrorHasDoc (VoidResult r)) => IsError (VoidResult r)

Defined in Lorentz.Macro

Methods

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

errorFromVal :: (Typeable t, SingI t) => Value t -> Either Text (VoidResult r)

(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)

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

Defined in Lorentz.Errors

Methods

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

errorFromVal :: (Typeable t, SingI t) => Value t -> Either Text (arg -> CustomError tag)

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

Implementation of errorToVal via IsoValue.

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

Implementation of errorFromVal via IsoValue.

class ErrorHasDoc e where

Minimal complete definition

errorDocName, errorDocMdCause, errorDocHaskellRep, errorDocDependencies

Methods

errorDocName :: Text

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

errorDocMdCause :: Markdown

What should happen for this error to be raised.

errorDocMdCauseInEntrypoint :: Markdown

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

How this error is represented in Haskell.

errorDocClass :: ErrorClass

Error class.

errorDocDependencies :: [SomeDocDefinitionItem]

Which definitions documentation for this error mentions.

Instances

(TypeError (Text "Use representative error messages") :: Constraint) => ErrorHasDoc ()

Defined in Lorentz.Errors

Methods

errorDocName :: Text

errorDocMdCause :: Markdown

errorDocMdCauseInEntrypoint :: Markdown

errorDocHaskellRep :: Markdown

errorDocClass :: ErrorClass

errorDocDependencies :: [SomeDocDefinitionItem]

ErrorHasDoc MText

Defined in Lorentz.Errors

Methods

errorDocName :: Text

errorDocMdCause :: Markdown

errorDocMdCauseInEntrypoint :: Markdown

errorDocHaskellRep :: Markdown

errorDocClass :: ErrorClass

errorDocDependencies :: [SomeDocDefinitionItem]

ErrorHasDoc UnspecifiedError

Defined in Lorentz.Errors

Methods

errorDocName :: Text

errorDocMdCause :: Markdown

errorDocMdCauseInEntrypoint :: Markdown

errorDocHaskellRep :: Markdown

errorDocClass :: ErrorClass

errorDocDependencies :: [SomeDocDefinitionItem]

(CustomErrorHasDoc tag, SingI (ToT (ErrorArg tag))) => ErrorHasDoc (CustomError tag :: Type)

Defined in Lorentz.Errors

Methods

errorDocName :: Text

errorDocMdCause :: Markdown

errorDocMdCauseInEntrypoint :: Markdown

errorDocHaskellRep :: Markdown

errorDocClass :: ErrorClass

errorDocDependencies :: [SomeDocDefinitionItem]

TypeHasDoc r => ErrorHasDoc (VoidResult r :: Type)

Defined in Lorentz.Macro

Methods

errorDocName :: Text

errorDocMdCause :: Markdown

errorDocMdCauseInEntrypoint :: Markdown

errorDocHaskellRep :: Markdown

errorDocClass :: ErrorClass

errorDocDependencies :: [SomeDocDefinitionItem]

ErrorHasDoc (CustomError tag) => ErrorHasDoc (arg -> CustomError tag :: Type)

Defined in Lorentz.Errors

Methods

errorDocName :: Text

errorDocMdCause :: Markdown

errorDocMdCauseInEntrypoint :: Markdown

errorDocHaskellRep :: Markdown

errorDocClass :: ErrorClass

errorDocDependencies :: [SomeDocDefinitionItem]

typeDocMdDescriptionReferToError :: forall e. IsError e => Markdown

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

data UnspecifiedError

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

Constructors

UnspecifiedError

Instances

Generic UnspecifiedError

Defined in Lorentz.Errors

Associated Types

type Rep UnspecifiedError :: Type -> Type

Methods

from :: UnspecifiedError -> Rep UnspecifiedError x

to :: Rep UnspecifiedError x -> UnspecifiedError

IsoValue UnspecifiedError

Defined in Lorentz.Errors

Associated Types

type ToT UnspecifiedError :: T

Methods

toVal :: UnspecifiedError -> Value (ToT UnspecifiedError)

fromVal :: Value (ToT UnspecifiedError) -> UnspecifiedError

IsError UnspecifiedError

Defined in Lorentz.Errors

Methods

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

errorFromVal :: (Typeable t, SingI t) => Value t -> Either Text UnspecifiedError

ErrorHasDoc UnspecifiedError

Defined in Lorentz.Errors

Methods

errorDocName :: Text

errorDocMdCause :: Markdown

errorDocMdCauseInEntrypoint :: Markdown

errorDocHaskellRep :: Markdown

errorDocClass :: ErrorClass

errorDocDependencies :: [SomeDocDefinitionItem]

type Rep UnspecifiedError

Defined in Lorentz.Errors

type Rep UnspecifiedError = D1 (MetaData "UnspecifiedError" "Lorentz.Errors" "morley-0.7.0-LSdrRUk5DEH474ZZZf5NDz" False) (C1 (MetaCons "UnspecifiedError" PrefixI False) (U1 :: Type -> Type))

type ToT UnspecifiedError

Defined in Lorentz.Errors

type ToT UnspecifiedError = GValueType (Rep UnspecifiedError)

General instructions

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

Fail with the given Haskell value.

failUnexpected :: MText -> s :-> t

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

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.

Instances

type ErrorArg "emptySupplied"

Someone constructed Empty type.

Defined in Lorentz.Empty

type ErrorArg "emptySupplied" = ()

type ErrorArg "senderIsNotAdmin"

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

Defined in Lorentz.Errors.Common

type ErrorArg "senderIsNotAdmin" = ()

type ErrorArg "uparamArgumentUnpackFailed"

Defined in Lorentz.UParam

type ErrorArg "uparamArgumentUnpackFailed" = ()

type ErrorArg "uparamNoSuchEntryPoint"

Defined in Lorentz.UParam

type ErrorArg "uparamNoSuchEntryPoint" = MText

data CustomError (tag :: Symbol)

Material custom error.

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

Constructors

CustomError

Fields

• ceTag :: Label tag
• ceArg :: ErrorArg tag

Instances

Eq (ErrorArg tag) => Eq (CustomError tag)

Defined in Lorentz.Errors

Methods

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

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

Show (ErrorArg tag) => Show (CustomError tag)

Defined in Lorentz.Errors

Methods

showsPrec :: Int -> CustomError tag -> ShowS

show :: CustomError tag -> String

showList :: [CustomError tag] -> ShowS

Buildable (CustomError "emptySupplied")

Defined in Lorentz.Empty

Methods

build :: CustomError "emptySupplied" -> Builder

Buildable (CustomError "senderIsNotAdmin")

Defined in Lorentz.Errors.Common

Methods

build :: CustomError "senderIsNotAdmin" -> Builder

Buildable (CustomError "uparamArgumentUnpackFailed")

Defined in Lorentz.UParam

Methods

build :: CustomError "uparamArgumentUnpackFailed" -> Builder

Buildable (CustomError "uparamNoSuchEntryPoint")

Defined in Lorentz.UParam

Methods

build :: CustomError "uparamNoSuchEntryPoint" -> Builder

(TypeError (Text "CustomError has no IsoValue instance") :: Constraint) => IsoValue (CustomError tag)

This instance cannot be implemented, use IsError instance instead.

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, KnownError (ErrorArg tag), IsoValue (ErrorArg tag)) => IsError (CustomError tag)

Defined in Lorentz.Errors

Methods

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

errorFromVal :: (Typeable t, SingI t) => Value t -> Either Text (CustomError tag)

(CustomErrorHasDoc tag, SingI (ToT (ErrorArg tag))) => ErrorHasDoc (CustomError tag :: Type)

Defined in Lorentz.Errors

Methods

errorDocName :: Text

errorDocMdCause :: Markdown

errorDocMdCauseInEntrypoint :: Markdown

errorDocHaskellRep :: Markdown

errorDocClass :: ErrorClass

errorDocDependencies :: [SomeDocDefinitionItem]

ErrorHasDoc (CustomError tag) => ErrorHasDoc (arg -> CustomError tag :: Type)

Defined in Lorentz.Errors

Methods

errorDocName :: Text

errorDocMdCause :: Markdown

errorDocMdCauseInEntrypoint :: Markdown

errorDocHaskellRep :: Markdown

errorDocClass :: ErrorClass

errorDocDependencies :: [SomeDocDefinitionItem]

Eq (ErrorArg tag) => Eq (() -> CustomError tag)

Defined in Lorentz.Errors

Methods

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

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

Show (ErrorArg tag) => Show (() -> CustomError tag)

Defined in Lorentz.Errors

Methods

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

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

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

(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)

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

Defined in Lorentz.Errors

Methods

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

errorFromVal :: (Typeable t, SingI t) => Value t -> Either Text (arg -> CustomError tag)

type ToT (CustomError tag)

Defined in Lorentz.Errors

type ToT (CustomError tag) = (TypeError (Text "CustomError has no IsoValue instance") :: T)

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

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)))

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

Specialization of failCustom for no-arg errors.

Documentation

data ErrorClass

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

Buildable ErrorClass

Defined in Lorentz.Errors

Methods

build :: ErrorClass -> Builder

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

Minimal complete definition

customErrDocMdCause, customErrClass

Methods

customErrDocMdCause :: Markdown

What should happen for this error to be raised.

customErrDocMdCauseInEntrypoint :: Markdown

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

Error class.

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

customErrArgumentSemantics :: Maybe Markdown

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

Instances

CustomErrorHasDoc "emptySupplied"

Defined in Lorentz.Empty

Methods

customErrDocMdCause :: Markdown

customErrDocMdCauseInEntrypoint :: Markdown

customErrClass :: ErrorClass

customErrArgumentSemantics :: Maybe Markdown

CustomErrorHasDoc "senderIsNotAdmin"

Defined in Lorentz.Errors.Common

Methods

customErrDocMdCause :: Markdown

customErrDocMdCauseInEntrypoint :: Markdown

customErrClass :: ErrorClass

customErrArgumentSemantics :: Maybe Markdown

CustomErrorHasDoc "uparamArgumentUnpackFailed"

Defined in Lorentz.UParam

Methods

customErrDocMdCause :: Markdown

customErrDocMdCauseInEntrypoint :: Markdown

customErrClass :: ErrorClass

customErrArgumentSemantics :: Maybe Markdown

CustomErrorHasDoc "uparamNoSuchEntryPoint"

Defined in Lorentz.UParam

Methods

customErrDocMdCause :: Markdown

customErrDocMdCauseInEntrypoint :: Markdown

customErrClass :: ErrorClass

customErrArgumentSemantics :: Maybe Markdown

data DError where

Mentions that contract uses given error.

Constructors

DError :: IsError e => Proxy e -> DError

Instances

Eq DError

Defined in Lorentz.Errors

Methods

(==) :: DError -> DError -> Bool

(/=) :: DError -> DError -> Bool

Ord DError

Defined in Lorentz.Errors

Methods

compare :: DError -> DError -> Ordering

(<) :: DError -> DError -> Bool

(<=) :: DError -> DError -> Bool

(>) :: DError -> DError -> Bool

(>=) :: DError -> DError -> Bool

max :: DError -> DError -> DError

min :: DError -> DError -> DError

DocItem DError

Defined in Lorentz.Errors

Associated Types

type DocItemPosition DError = (pos :: Nat)

type DocItemPlacement DError :: DocItemPlacementKind

Methods

docItemSectionName :: Maybe Text

docItemSectionDescription :: Maybe Markdown

docItemSectionNameStyle :: DocSectionNameStyle

docItemRef :: DError -> DocItemRef (DocItemPlacement DError)

docItemToMarkdown :: HeaderLevel -> DError -> Markdown

docItemDependencies :: DError -> [SomeDocDefinitionItem]

docItemsOrder :: [DError] -> [DError]

type DocItemPosition DError

Defined in Lorentz.Errors

type DocItemPosition DError = 5010

type DocItemPlacement DError

Defined in Lorentz.Errors

type DocItemPlacement DError = DocItemInDefinitions

data DThrows where

Documentation for custom errors.

Mentions that entrypoint throws given error.

Constructors

DThrows :: IsError e => Proxy e -> DThrows

Instances

Eq DThrows

Defined in Lorentz.Errors

Methods

(==) :: DThrows -> DThrows -> Bool

(/=) :: DThrows -> DThrows -> Bool

DocItem DThrows

Defined in Lorentz.Errors

Associated Types

type DocItemPosition DThrows = (pos :: Nat)

type DocItemPlacement DThrows :: DocItemPlacementKind

Methods

docItemSectionName :: Maybe Text

docItemSectionDescription :: Maybe Markdown

docItemSectionNameStyle :: DocSectionNameStyle

docItemRef :: DThrows -> DocItemRef (DocItemPlacement DThrows)

docItemToMarkdown :: HeaderLevel -> DThrows -> Markdown

docItemDependencies :: DThrows -> [SomeDocDefinitionItem]

docItemsOrder :: [DThrows] -> [DThrows]

type DocItemPosition DThrows

Defined in Lorentz.Errors

type DocItemPosition DThrows = 5011

type DocItemPlacement DThrows

Defined in Lorentz.Errors

type DocItemPlacement DThrows = DocItemInlined

Old interface (DEPRECATED)

customErrorToVal :: (LooseSumC e, HasCallStack) => e -> (forall t. ErrorScope t => Value t -> r) -> r

Deprecated: Datatype error declarations has been deprecated

Implementation of errorToVal for custom errors.

customErrorFromVal :: forall t e. (SingI t, LooseSumC e) => Value t -> Either Text e

Deprecated: Datatype error declarations has been deprecated

Implementation of errorFromVal for custom errors.

This function is deprecated.

failUsingArg :: forall err name fieldTy s s'. FailUsingArg err name fieldTy s s'

Deprecated: Datatype error declarations has been deprecated

Fail with given error, picking argument for error from the top of the stack.

If your error constructor does not carry an argument, use failUsing function instead. Consider the following practice: once error datatype for your contract is defined, create a specialization of this function to the error type.

This function is deprecated.

type FailUsingArg e name fieldTy s s' = (KnownSymbol name, IsError e, IsoValue fieldTy, CtorHasOnlyField name e fieldTy, Each [Typeable, SingI] '[ToT fieldTy], HasCallStack) => Label name -> (fieldTy ': s) :-> s'

Signature of userFailWith.

type family CustomErrorNoIsoValue a where ...

Prompt an error message saying that IsoValue is not applicable for this type.

Equations

CustomErrorNoIsoValue a = TypeError ((Text "No IsoValue instance for " :<>: ShowType a) :$$: Text "It has custom error representation")

deriveCustomError :: Name -> Q [Dec]

Deprecated: Datatype error declarations has been deprecated

Derive IsError instance for given type.

This will also forbid deriving IsoValue instance for that type to avoid having multiple different Michelson representations.

errorsDocumentation :: Markdown

This is to be included on top of Errors section of the generated documentation.