| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Lorentz.Errors
Synopsis
- class (Typeable e, ErrorHasDoc e) => IsError e where
- errorToVal :: e -> (forall t. ErrorScope t => Value t -> r) -> r
- errorFromVal :: KnownT t => Value t -> Either Text e
- type ErrorScope t = (Typeable t, ConstantScope t)
- isoErrorToVal :: (KnownError e, IsoValue e) => e -> (forall t. ErrorScope t => Value t -> r) -> r
- isoErrorFromVal :: (Typeable t, Typeable (ToT e), IsoValue e) => Value t -> Either Text e
- class Typeable e => ErrorHasDoc (e :: Type) where
- typeDocMdDescriptionReferToError :: forall e. IsError e => Markdown
- customErrorDocHaskellRepGeneral :: (SingI (ToT (ErrorArg tag)), IsError (CustomError tag), TypeHasDoc (ErrorArg tag), CustomErrorHasDoc tag) => Text -> Proxy tag -> Markdown
- data UnspecifiedError = UnspecifiedError
- data SomeError = forall e.(IsError e, Eq e) => SomeError e
- failUsing :: forall e s t. IsError e => e -> s :-> t
- failUnexpected :: MText -> s :-> t
- type family ErrorArg (tag :: Symbol) :: Type
- data CustomError (tag :: Symbol) = CustomError {}
- failCustom :: forall tag err s any. (err ~ ErrorArg tag, CustomErrorHasDoc tag, KnownError err) => Label tag -> (err ': s) :-> any
- 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
- data ErrorClass
- class (KnownSymbol tag, TypeHasDoc (ErrorArg tag), IsError (CustomError tag)) => CustomErrorHasDoc tag where
- data DError where
- DError :: ErrorHasDoc e => Proxy e -> DError
- data DThrows where
- DThrows :: ErrorHasDoc e => Proxy e -> DThrows
- errorTagToText :: forall tag. KnownSymbol tag => Text
- errorTagToMText :: Label tag -> MText
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
| (TypeError ('Text "Use representative error messages") :: Constraint) => IsError () Source # | |
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. |
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 # | |
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 # | |
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 # | |
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 |
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 #
Minimal complete definition
errorDocName, errorDocMdCause, errorDocHaskellRep, errorDocDependencies
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.
type ErrorRequirements e = () Source #
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.
default errorDocRequirements :: ErrorRequirements e => Dict (ErrorRequirements e) Source #
Instances
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
Type wrapper for an IsError.
General instructions
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
| type ErrorArg "emptySupplied" Source # | Someone constructed |
Defined in Lorentz.Empty type ErrorArg "emptySupplied" = () | |
| type ErrorArg "senderIsNotAdmin" Source # | Contract initiator should be contract admin in order to perform this operation. |
Defined in Lorentz.Errors.Common type ErrorArg "senderIsNotAdmin" = () | |
| type ErrorArg "uparamArgumentUnpackFailed" Source # | |
Defined in Lorentz.UParam type ErrorArg "uparamArgumentUnpackFailed" = () | |
| type ErrorArg "uparamNoSuchEntrypoint" Source # | |
Defined in Lorentz.UParam | |
data CustomError (tag :: Symbol) Source #
Material custom error.
Use this in pattern matches against error (e.g. in tests).
Constructors
| CustomError | |
Instances
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 |
| 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
| Read ErrorClass Source # | |
Defined in Lorentz.Errors Methods readsPrec :: Int -> ReadS ErrorClass # readList :: ReadS [ErrorClass] # readPrec :: ReadPrec ErrorClass # readListPrec :: ReadPrec [ErrorClass] # | |
| Lift ErrorClass Source # | |
Defined in Lorentz.Errors Methods lift :: ErrorClass -> Q Exp # | |
| Buildable ErrorClass Source # | |
Defined in Lorentz.Errors Methods build :: ErrorClass -> Builder # | |
class (KnownSymbol tag, TypeHasDoc (ErrorArg tag), IsError (CustomError tag)) => CustomErrorHasDoc tag where Source #
Minimal complete definition
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
Instances
| CustomErrorHasDoc "emptySupplied" Source # | |
Defined in Lorentz.Empty | |
| CustomErrorHasDoc "senderIsNotAdmin" Source # | |
| CustomErrorHasDoc "uparamArgumentUnpackFailed" Source # | |
Defined in Lorentz.UParam | |
| CustomErrorHasDoc "uparamNoSuchEntrypoint" Source # | |
Defined in Lorentz.UParam | |
Mentions that contract uses given error.
Constructors
| DError :: ErrorHasDoc e => Proxy e -> DError |
Instances
| Eq DError Source # | |
| Ord DError Source # | |
| DocItem DError Source # | |
Defined in Lorentz.Errors Associated Types type DocItemPlacement DError :: DocItemPlacementKind # type DocItemReferenced DError :: DocItemReferencedKind # Methods docItemPos :: Natural # docItemSectionName :: Maybe Text # docItemSectionDescription :: Maybe Markdown # docItemSectionNameStyle :: DocSectionNameStyle # docItemRef :: DError -> DocItemRef (DocItemPlacement DError) (DocItemReferenced DError) # docItemToMarkdown :: HeaderLevel -> DError -> Markdown # docItemToToc :: HeaderLevel -> DError -> Markdown # docItemDependencies :: DError -> [SomeDocDefinitionItem] # docItemsOrder :: [DError] -> [DError] # | |
| type DocItemPlacement DError Source # | |
Defined in Lorentz.Errors | |
| type DocItemReferenced DError Source # | |
Defined in Lorentz.Errors | |
Documentation for custom errors.
Mentions that entrypoint throws given error.
Constructors
| DThrows :: ErrorHasDoc e => Proxy e -> DThrows |
Instances
| Eq DThrows Source # | |
| DocItem DThrows Source # | |
Defined in Lorentz.Errors Associated Types type DocItemPlacement DThrows :: DocItemPlacementKind # type DocItemReferenced DThrows :: DocItemReferencedKind # Methods docItemPos :: Natural # docItemSectionName :: Maybe Text # docItemSectionDescription :: Maybe Markdown # docItemSectionNameStyle :: DocSectionNameStyle # docItemRef :: DThrows -> DocItemRef (DocItemPlacement DThrows) (DocItemReferenced DThrows) # docItemToMarkdown :: HeaderLevel -> DThrows -> Markdown # docItemToToc :: HeaderLevel -> DThrows -> Markdown # docItemDependencies :: DThrows -> [SomeDocDefinitionItem] # docItemsOrder :: [DThrows] -> [DThrows] # | |
| type DocItemPlacement DThrows Source # | |
Defined in Lorentz.Errors | |
| type DocItemReferenced DThrows Source # | |
Defined in Lorentz.Errors | |
Internals
errorTagToText :: forall tag. KnownSymbol tag => Text Source #
errorTagToMText :: Label tag -> MText Source #
Demote error tag to term level.