Safe Haskell	Safe
Language	Haskell2010

Bio.Iteratee.Exception

Contents

Exception types
- Enumerator exceptions
- Iteratee exceptions
Functions

Description

Monadic and General Iteratees: Messaging and exception handling.

Iteratees use an internal exception handling mechanism that is parallel to that provided by Exception. This allows the iteratee framework to handle its own exceptions outside IO.

Iteratee exceptions are divided into two categories, IterException and EnumException. IterExceptions are exceptions within an iteratee, and EnumExceptions are exceptions within an enumerator.

Enumerators can be constructed to handle an IterException with Data.Iteratee.Iteratee.enumFromCallbackCatch. If the enumerator detects an iteratee exception, the enumerator calls the provided exception handler. The enumerator is then able to continue feeding data to the iteratee, provided the exception was successfully handled. If the handler could not handle the exception, the IterException is converted to an EnumException and processing aborts.

Exceptions can also be cleared by Data.Iteratee.Iteratee.checkErr, although in this case the iteratee continuation cannot be recovered.

When viewed as Resumable Exceptions, iteratee exceptions provide a means for iteratees to send control messages to enumerators. The seek implementation provides an example. Data.Iteratee.Iteratee.seek stores the current iteratee continuation and throws a SeekException, which inherits from IterException. Data.Iteratee.IO.enumHandleRandom is constructed with enumFromCallbackCatch and a handler that performs an hSeek. Upon receiving the SeekException, enumHandleRandom calls the handler, checks that it executed properly, and then continues with the stored continuation.

As the exception hierarchy is open, users can extend it with custom exceptions and exception handlers to implement sophisticated messaging systems based upon resumable exceptions.

Synopsis

data IFException = Exception e => IFException e
class (Typeable e, Show e) => Exception e where
type FileOffset = COff
data EnumException = Exception e => EnumException e
data DivergentException = DivergentException
newtype EnumStringException = EnumStringException String
newtype EnumUnhandledIterException = EnumUnhandledIterException IterException
class Exception e => IException e where
data IterException = Exception e => IterException e
newtype SeekException = SeekException FileOffset
data EofException = EofException
newtype IterStringException = IterStringException String
enStrExc :: String -> EnumException
iterStrExc :: String -> SomeException
wrapIterExc :: IterException -> EnumException
iterExceptionToException :: Exception e => e -> SomeException
iterExceptionFromException :: Exception e => SomeException -> Maybe e

Exception types

data IFException Source #

Root of the Iteratee exception hierarchy. IFException derives from Control.Exception.SomeException. EnumException, IterException, and all inheritants are descendents of IFException.

Constructors

Exception e => IFException e

Instances

Show IFException Source #
Instance details Defined in Bio.Iteratee.Exception Methods showsPrec :: Int -> IFException -> ShowS # show :: IFException -> String # showList :: [IFException] -> ShowS #
Exception IFException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: IFException -> SomeException # fromException :: SomeException -> Maybe IFException # displayException :: IFException -> String #

class (Typeable e, Show e) => Exception e where #

Any type that you wish to throw or catch as an exception must be an instance of the Exception class. The simplest case is a new exception type directly below the root:

data MyException = ThisException | ThatException
    deriving Show

instance Exception MyException

The default method definitions in the Exception class do what we need in this case. You can now throw and catch ThisException and ThatException as exceptions:

*Main> throw ThisException `catch` \e -> putStrLn ("Caught " ++ show (e :: MyException))
Caught ThisException

In more complicated examples, you may wish to define a whole hierarchy of exceptions:

---------------------------------------------------------------------
-- Make the root exception type for all the exceptions in a compiler

data SomeCompilerException = forall e . Exception e => SomeCompilerException e

instance Show SomeCompilerException where
    show (SomeCompilerException e) = show e

instance Exception SomeCompilerException

compilerExceptionToException :: Exception e => e -> SomeException
compilerExceptionToException = toException . SomeCompilerException

compilerExceptionFromException :: Exception e => SomeException -> Maybe e
compilerExceptionFromException x = do
    SomeCompilerException a <- fromException x
    cast a

---------------------------------------------------------------------
-- Make a subhierarchy for exceptions in the frontend of the compiler

data SomeFrontendException = forall e . Exception e => SomeFrontendException e

instance Show SomeFrontendException where
    show (SomeFrontendException e) = show e

instance Exception SomeFrontendException where
    toException = compilerExceptionToException
    fromException = compilerExceptionFromException

frontendExceptionToException :: Exception e => e -> SomeException
frontendExceptionToException = toException . SomeFrontendException

frontendExceptionFromException :: Exception e => SomeException -> Maybe e
frontendExceptionFromException x = do
    SomeFrontendException a <- fromException x
    cast a

---------------------------------------------------------------------
-- Make an exception type for a particular frontend compiler exception

data MismatchedParentheses = MismatchedParentheses
    deriving Show

instance Exception MismatchedParentheses where
    toException   = frontendExceptionToException
    fromException = frontendExceptionFromException

We can now catch a MismatchedParentheses exception as MismatchedParentheses, SomeFrontendException or SomeCompilerException, but not other types, e.g. IOException:

*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: MismatchedParentheses))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeFrontendException))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: SomeCompilerException))
Caught MismatchedParentheses
*Main> throw MismatchedParentheses `catch` \e -> putStrLn ("Caught " ++ show (e :: IOException))
*** Exception: MismatchedParentheses

Methods

toException :: e -> SomeException #

fromException :: SomeException -> Maybe e #

displayException :: e -> String #

Render this exception value in a human-friendly manner.

Default implementation: show.

Since: base-4.8.0.0

Instances

Exception AsyncCancelled
Instance details Defined in Control.Concurrent.Async Methods toException :: AsyncCancelled -> SomeException # fromException :: SomeException -> Maybe AsyncCancelled # displayException :: AsyncCancelled -> String #
Exception ExceptionInLinkedThread
Instance details Defined in Control.Concurrent.Async Methods toException :: ExceptionInLinkedThread -> SomeException # fromException :: SomeException -> Maybe ExceptionInLinkedThread # displayException :: ExceptionInLinkedThread -> String #
Exception Void	Since: base-4.8.0.0
Instance details Defined in Data.Void Methods toException :: Void -> SomeException # fromException :: SomeException -> Maybe Void # displayException :: Void -> String #
Exception PatternMatchFail	Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: PatternMatchFail -> SomeException # fromException :: SomeException -> Maybe PatternMatchFail # displayException :: PatternMatchFail -> String #
Exception RecSelError	Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: RecSelError -> SomeException # fromException :: SomeException -> Maybe RecSelError # displayException :: RecSelError -> String #
Exception RecConError	Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: RecConError -> SomeException # fromException :: SomeException -> Maybe RecConError # displayException :: RecConError -> String #
Exception RecUpdError	Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: RecUpdError -> SomeException # fromException :: SomeException -> Maybe RecUpdError # displayException :: RecUpdError -> String #
Exception NoMethodError	Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: NoMethodError -> SomeException # fromException :: SomeException -> Maybe NoMethodError # displayException :: NoMethodError -> String #
Exception TypeError	Since: base-4.9.0.0
Instance details Defined in Control.Exception.Base Methods toException :: TypeError -> SomeException # fromException :: SomeException -> Maybe TypeError # displayException :: TypeError -> String #
Exception NonTermination	Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: NonTermination -> SomeException # fromException :: SomeException -> Maybe NonTermination # displayException :: NonTermination -> String #
Exception NestedAtomically	Since: base-4.0
Instance details Defined in Control.Exception.Base Methods toException :: NestedAtomically -> SomeException # fromException :: SomeException -> Maybe NestedAtomically # displayException :: NestedAtomically -> String #
Exception Dynamic	Since: base-4.0.0.0
Instance details Defined in Data.Dynamic Methods toException :: Dynamic -> SomeException # fromException :: SomeException -> Maybe Dynamic # displayException :: Dynamic -> String #
Exception BlockedIndefinitelyOnMVar	Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: BlockedIndefinitelyOnMVar -> SomeException # fromException :: SomeException -> Maybe BlockedIndefinitelyOnMVar # displayException :: BlockedIndefinitelyOnMVar -> String #
Exception BlockedIndefinitelyOnSTM	Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: BlockedIndefinitelyOnSTM -> SomeException # fromException :: SomeException -> Maybe BlockedIndefinitelyOnSTM # displayException :: BlockedIndefinitelyOnSTM -> String #
Exception Deadlock	Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: Deadlock -> SomeException # fromException :: SomeException -> Maybe Deadlock # displayException :: Deadlock -> String #
Exception AllocationLimitExceeded	Since: base-4.8.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: AllocationLimitExceeded -> SomeException # fromException :: SomeException -> Maybe AllocationLimitExceeded # displayException :: AllocationLimitExceeded -> String #
Exception CompactionFailed	Since: base-4.10.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: CompactionFailed -> SomeException # fromException :: SomeException -> Maybe CompactionFailed # displayException :: CompactionFailed -> String #
Exception AssertionFailed	Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: AssertionFailed -> SomeException # fromException :: SomeException -> Maybe AssertionFailed # displayException :: AssertionFailed -> String #
Exception SomeAsyncException	Since: base-4.7.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: SomeAsyncException -> SomeException # fromException :: SomeException -> Maybe SomeAsyncException # displayException :: SomeAsyncException -> String #
Exception AsyncException	Since: base-4.7.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: AsyncException -> SomeException # fromException :: SomeException -> Maybe AsyncException # displayException :: AsyncException -> String #
Exception ArrayException	Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: ArrayException -> SomeException # fromException :: SomeException -> Maybe ArrayException # displayException :: ArrayException -> String #
Exception FixIOException	Since: base-4.11.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: FixIOException -> SomeException # fromException :: SomeException -> Maybe FixIOException # displayException :: FixIOException -> String #
Exception ExitCode	Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: ExitCode -> SomeException # fromException :: SomeException -> Maybe ExitCode # displayException :: ExitCode -> String #
Exception IOException	Since: base-4.1.0.0
Instance details Defined in GHC.IO.Exception Methods toException :: IOException -> SomeException # fromException :: SomeException -> Maybe IOException # displayException :: IOException -> String #
Exception ErrorCall	Since: base-4.0.0.0
Instance details Defined in GHC.Exception Methods toException :: ErrorCall -> SomeException # fromException :: SomeException -> Maybe ErrorCall # displayException :: ErrorCall -> String #
Exception ArithException	Since: base-4.0.0.0
Instance details Defined in GHC.Exception Methods toException :: ArithException -> SomeException # fromException :: SomeException -> Maybe ArithException # displayException :: ArithException -> String #
Exception SomeException	Since: base-3.0
Instance details Defined in GHC.Exception Methods toException :: SomeException -> SomeException # fromException :: SomeException -> Maybe SomeException # displayException :: SomeException -> String #
Exception UnicodeException
Instance details Defined in Data.Text.Encoding.Error Methods toException :: UnicodeException -> SomeException # fromException :: SomeException -> Maybe UnicodeException # displayException :: UnicodeException -> String #
Exception DecompressError
Instance details Defined in Codec.Compression.Zlib.Internal Methods toException :: DecompressError -> SomeException # fromException :: SomeException -> Maybe DecompressError # displayException :: DecompressError -> String #
Exception IterStringException #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: IterStringException -> SomeException # fromException :: SomeException -> Maybe IterStringException # displayException :: IterStringException -> String #
Exception EofException #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: EofException -> SomeException # fromException :: SomeException -> Maybe EofException # displayException :: EofException -> String #
Exception SeekException #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: SeekException -> SomeException # fromException :: SomeException -> Maybe SeekException # displayException :: SeekException -> String #
Exception IterException #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: IterException -> SomeException # fromException :: SomeException -> Maybe IterException # displayException :: IterException -> String #
Exception EnumUnhandledIterException #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: EnumUnhandledIterException -> SomeException # fromException :: SomeException -> Maybe EnumUnhandledIterException # displayException :: EnumUnhandledIterException -> String #
Exception EnumStringException #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: EnumStringException -> SomeException # fromException :: SomeException -> Maybe EnumStringException # displayException :: EnumStringException -> String #
Exception DivergentException #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: DivergentException -> SomeException # fromException :: SomeException -> Maybe DivergentException # displayException :: DivergentException -> String #
Exception EnumException #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: EnumException -> SomeException # fromException :: SomeException -> Maybe EnumException # displayException :: EnumException -> String #
Exception IFException #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: IFException -> SomeException # fromException :: SomeException -> Maybe IFException # displayException :: IFException -> String #
Exception Timeout	Since: base-4.7.0.0
Instance details Defined in System.Timeout Methods toException :: Timeout -> SomeException # fromException :: SomeException -> Maybe Timeout # displayException :: Timeout -> String #
Exception ParseError #
Instance details Defined in Bio.Iteratee Methods toException :: ParseError -> SomeException # fromException :: SomeException -> Maybe ParseError # displayException :: ParseError -> String #
Exception ZLibException #
Instance details Defined in Bio.Iteratee.ZLib Methods toException :: ZLibException -> SomeException # fromException :: SomeException -> Maybe ZLibException # displayException :: ZLibException -> String #
Exception ZLibParamsException #
Instance details Defined in Bio.Iteratee.ZLib Methods toException :: ZLibParamsException -> SomeException # fromException :: SomeException -> Maybe ZLibParamsException # displayException :: ZLibParamsException -> String #

type FileOffset = COff #

Enumerator exceptions

data EnumException Source #

Constructors

Exception e => EnumException e

Instances

Show EnumException Source #
Instance details Defined in Bio.Iteratee.Exception Methods showsPrec :: Int -> EnumException -> ShowS # show :: EnumException -> String # showList :: [EnumException] -> ShowS #
Exception EnumException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: EnumException -> SomeException # fromException :: SomeException -> Maybe EnumException # displayException :: EnumException -> String #

data DivergentException Source #

The iteratee diverged upon receiving EOF.

Constructors

DivergentException

Instances

Show DivergentException Source #
Instance details Defined in Bio.Iteratee.Exception Methods showsPrec :: Int -> DivergentException -> ShowS # show :: DivergentException -> String # showList :: [DivergentException] -> ShowS #
Exception DivergentException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: DivergentException -> SomeException # fromException :: SomeException -> Maybe DivergentException # displayException :: DivergentException -> String #

newtype EnumStringException Source #

Create an enumerator exception from a String.

Constructors

EnumStringException String

Instances

Show EnumStringException Source #
Instance details Defined in Bio.Iteratee.Exception Methods showsPrec :: Int -> EnumStringException -> ShowS # show :: EnumStringException -> String # showList :: [EnumStringException] -> ShowS #
Exception EnumStringException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: EnumStringException -> SomeException # fromException :: SomeException -> Maybe EnumStringException # displayException :: EnumStringException -> String #

newtype EnumUnhandledIterException Source #

The enumerator received an IterException it could not handle.

Constructors

EnumUnhandledIterException IterException

Instances

Show EnumUnhandledIterException Source #
Instance details Defined in Bio.Iteratee.Exception Methods showsPrec :: Int -> EnumUnhandledIterException -> ShowS # show :: EnumUnhandledIterException -> String # showList :: [EnumUnhandledIterException] -> ShowS #
Exception EnumUnhandledIterException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: EnumUnhandledIterException -> SomeException # fromException :: SomeException -> Maybe EnumUnhandledIterException # displayException :: EnumUnhandledIterException -> String #

Iteratee exceptions

class Exception e => IException e where Source #

A class for iteratee exceptions. Only inheritants of IterException should be instances of this class.

Methods

toIterException :: e -> IterException Source #

fromIterException :: IterException -> Maybe e Source #

Instances

IException IterStringException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toIterException :: IterStringException -> IterException Source # fromIterException :: IterException -> Maybe IterStringException Source #
IException EofException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toIterException :: EofException -> IterException Source # fromIterException :: IterException -> Maybe EofException Source #
IException SeekException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toIterException :: SeekException -> IterException Source # fromIterException :: IterException -> Maybe SeekException Source #
IException IterException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toIterException :: IterException -> IterException Source # fromIterException :: IterException -> Maybe IterException Source #

data IterException Source #

Root of iteratee exceptions.

Constructors

Exception e => IterException e

Instances

Show IterException Source #
Instance details Defined in Bio.Iteratee.Exception Methods showsPrec :: Int -> IterException -> ShowS # show :: IterException -> String # showList :: [IterException] -> ShowS #
Exception IterException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: IterException -> SomeException # fromException :: SomeException -> Maybe IterException # displayException :: IterException -> String #
IException IterException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toIterException :: IterException -> IterException Source # fromIterException :: IterException -> Maybe IterException Source #

newtype SeekException Source #

A seek request within an Iteratee.

Constructors

SeekException FileOffset

Instances

Show SeekException Source #
Instance details Defined in Bio.Iteratee.Exception Methods showsPrec :: Int -> SeekException -> ShowS # show :: SeekException -> String # showList :: [SeekException] -> ShowS #
Exception SeekException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: SeekException -> SomeException # fromException :: SomeException -> Maybe SeekException # displayException :: SeekException -> String #
IException SeekException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toIterException :: SeekException -> IterException Source # fromIterException :: IterException -> Maybe SeekException Source #

data EofException Source #

The Iteratee needs more data but received EOF.

Constructors

EofException

Instances

Show EofException Source #
Instance details Defined in Bio.Iteratee.Exception Methods showsPrec :: Int -> EofException -> ShowS # show :: EofException -> String # showList :: [EofException] -> ShowS #
Exception EofException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: EofException -> SomeException # fromException :: SomeException -> Maybe EofException # displayException :: EofException -> String #
IException EofException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toIterException :: EofException -> IterException Source # fromIterException :: IterException -> Maybe EofException Source #

newtype IterStringException Source #

An Iteratee exception specified by a String.

Constructors

IterStringException String

Instances

Show IterStringException Source #
Instance details Defined in Bio.Iteratee.Exception Methods showsPrec :: Int -> IterStringException -> ShowS # show :: IterStringException -> String # showList :: [IterStringException] -> ShowS #
Exception IterStringException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toException :: IterStringException -> SomeException # fromException :: SomeException -> Maybe IterStringException # displayException :: IterStringException -> String #
IException IterStringException Source #
Instance details Defined in Bio.Iteratee.Exception Methods toIterException :: IterStringException -> IterException Source # fromIterException :: IterException -> Maybe IterStringException Source #

Functions

enStrExc :: String -> EnumException Source #

Create an EnumException from a string.

iterStrExc :: String -> SomeException Source #

Create an iteratee exception from a string. This convenience function wraps IterStringException and toException.

wrapIterExc :: IterException -> EnumException Source #

Convert an IterException to an EnumException. Meant to be used within an Enumerator to signify that it could not handle the IterException.

iterExceptionToException :: Exception e => e -> SomeException Source #

iterExceptionFromException :: Exception e => SomeException -> Maybe e Source #